Tlds

Overview

Tld (Top level domain) entries are used to manage the Tlds that Designate recognizes. By default, only an admin can manage these entries. The Tlds are stored in the Database/Storage in the table tlds and are not propagated to the DNS Backend. By default when Designate starts up there are no Tlds in the database.

Tld Checks

When there are no Tld entries in the database, Tld checks are not enforced and any domain/zone name can be created, as long as it adheres to the domain name schema. When there are Tlds present in the database, then when a domain/zone is created the name has to pass the following checks.

1. The last label in the domain/zone name must be present as a Tld entry in the database. e.g. If a domain/zone with the name example.com. is being created then the entry com must be present in the database.
2. The domain/zone name must not be present as a Tld entry in the database. e.g. If there is a Tld entry co.uk in the database, then a domain/zone with the name co.uk. cannot be created.

Create Tld

POST /tlds

Create a tld. name is the only entry that is required. The name should not end in a period (.).

Example request:

POST /tlds HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json

{
    "name" : "com",
    "description" : "Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9

{
    "description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
    "links":{
      "self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9"
    },
    "created_at":"2014-01-23T18:39:26.710827",
    "updated_at":null,
    "id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9",
    "name":"com"
}

Form Parameters:  

• created_at – timestamp
• updated_at – timestamp
• name – tld name
• id – uuid
• description – UTF-8 text field
• links – links to traverse the list

Status Codes:

• 201 Created – Created
• 401 Unauthorized – Access Denied
• 400 Bad Request – Invalid Object
• 409 Conflict – Duplicate Tld

Get a Tld

GET /tlds/(uuid: id)

Lists a particular Tld

Example request:

GET /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
    "links":{
      "self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9"
    },
    "created_at":"2014-01-23T18:39:26.710827",
    "updated_at":null,
    "id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9",
    "name":"com"
}

Form Parameters:  

• created_at – timestamp
• updated_at – timestamp
• name – tld name
• id – uuid
• description – UTF-8 text field
• links – links to traverse the list

Status Codes:

• 200 OK – OK
• 401 Unauthorized – Access Denied
• 404 Not Found – Tld not found

List Tlds

GET /tlds

Lists all tlds

Example request:

GET /tlds HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "tlds":[
    {
      "description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
      "links":{
        "self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9"
      },
      "created_at":"2014-01-23T18:39:26.710827",
      "updated_at":null,
      "id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9",
      "name":"com"
    },
    {
      "description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
      "links":{
        "self":"http://127.0.0.1:9001/v2/tlds/46e50ebc-1b51-41ee-bc1f-8e75a470c5be"
      },
      "created_at":"2014-01-23T19:59:53.985455",
      "updated_at":null,
      "id":"46e50ebc-1b51-41ee-bc1f-8e75a470c5be",
      "name":"net"
    }
  ],
  "links":{
    "self":"http://127.0.0.1:9001/v2/tlds"
  }
}

Form Parameters:  

• created_at – timestamp
• updated_at – timestamp
• name – tld name
• id – uuid
• description – UTF-8 text field
• links – links to traverse the list

Status Codes:

• 200 OK – OK
• 401 Unauthorized – Access Denied

Update a Tld

PATCH /tlds/(uuid: id)

updates a tld

Example request:

PATCH /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json

{
    "name" : "org",
    "description" : "Updated the name from com to org"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "description":"Updated the name from com to org",
    "links":{
      "self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9"
    },
    "created_at":"2014-01-23T18:39:26.710827",
    "updated_at":"2014-01-23T20:35:12.449599",
    "id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9",
    "name":"org"
}

Form Parameters:  

• created_at – timestamp
• updated_at – timestamp
• name – tld name
• id – uuid
• description – UTF-8 text field
• links – links to traverse the list

Status Codes:

• 200 OK – OK
• 401 Unauthorized – Access Denied
• 404 Not Found – Tld not found
• 409 Conflict – Duplicate Tld

Delete a Tld

DELETE /tlds/(uuid: id)

delete a tld

Example request:

DELETE /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 204 No Content
Content-Type: application/json; charset=UTF-8
Content-Length: 0

Status Codes:

• 204 No Content – No Content
• 401 Unauthorized – Access Denied
• 404 Not Found – Tld not found