Designate/Blueprints/TLD API

Overview

Gerrit Patch	[]
Launchpad Blueprint	[1]

This blueprint proposes to provide an admin-only API call to dynamically manage TLDs and effective TLDs. Currently, the list of TLDs resides in 2 files specified in the config file. Designate must be restarted before any changes to the .config file take place. One possible solution to this could be to make the .config file reloadable without restarting the Designate service. However, there are only limited Operations personnel who have access to the .config file, and the TLD and effective TLD files. Of late TLDs and effective TLDs are being added more often. When a customer needs to create a domain in a new TLD, it needs to be done quickly. Providing an API call would allow support personnel to be given admin rights to this API call so that they can effectively make the change in a timely manner, without trying to find the one or two people who can change the .config file and the TLD and effective TLD files

To implement this management capability, a new API call will be created, along with a new database table to store the TLDs, and they will no longer be in the files specified in the .config file.

API Resource

One new resource, tlds will be exposed as part of the Designate API. The TLD resource will allow authorized users to create/delete a new TLD or effective TLD. The resource is called "tlds", rather than "tld" so that it is similar to other resources - "domains", "servers", "records".

The TLD resource provides the following data:

• id – A system-defined UUID assigned to the TLD when it is created for the first time (required)
• name – The name of the TLD (required)
• created_at – Timestamp the TLD was created (required)
• updated_at – Timestamp the TLD entry was updated (can be null)
• description – UTF-8 text field (optional)

API Details: Create / List / Delete Instance

Verb	Resource	Description
GET	/tlds	Returns the list of TLDs
GET	/tlds/{id}	Returns a specific TLD
POST	/tlds	Creates a new tld entry based on the parameters supplied in the request body
PUT	No Op	A PUT is not needed
DELETE	/tlds/{id}	Deletes the tld entry. No message body is expected in the request

Get TLDs (GET)

When no id is specified all TLD entries are returned. If an id is specified in the URL, then only the specific TLD entry corresponding to that id is returned.

There is no request message body in either case.

Response

   {
       “tlds”: [
           {
               “id”: "2e32e609-3a4f-45ba-bdef-e50eacd34560",
               “name”: “com”,
               "created_at": "2013-12-09T19:56:26.000000",      
               “description”: "obtained from http://data.iana.org/TLD/tlds-alpha-by-domain.txt"
           },
           {
               “id”: "2e32e609-3a4f-45ba-bdef-e50eacd34561",
               “name”: “co.uk”,
               “created_at”: “2013-12-09T19:56:27.000000",      
               “description”: "obtained from http://mozilla.org/MPL/2.0/"
             }
         ]
   }

Create a TLD entry (POST)

When creating a TLD entry, the caller must supply the TLD name. The wildcard character * (asterisk) may (only) be used to wildcard the topmost level in a domain name.

Request

   {
       “tlds”: {
           “name”: “*.bd”,
           “description”: "obtained from http://publicsuffix.org"
       }
    }

Response

   {
       “tlds”: {
           {
              “id”: "2e32e609-3a4f-45ba-bdef-e50eacd34560",
              “name”: “*.bd”,
              "created_at": "2013-12-09T19:56:26.000000",      
              “description”: "obtained from http://publicsuffix.org"
           }
       }
   }

Update a TLD (PUT)

No operation. An call is not needed to update a single TLD entry. The user would delete the TLD they did not want and add a new one, if desired.

Delete a TLD (DELETE)

When deleting a TLD entry, the user must supply the id in the url. The request body is empty. The return body is empty.

Database Schema

A new table will be created in the Designate database: "tlds", which will store the TLD name, along with other data. The fields id, version, created_at and updated_at are inherited.

Name	Data Type	Length	Nullable	Details
id	VARCHAR	36	False	Primary Key, Generated UUID
version	INTEGER	-	False	Designate API version
created_at	DATETIME	-	False	UTC time of creation
updated_at	DATETIME	-	True	UTC time of updation
name	VARCHAR	255	False	TLD name
description	VARCHAR	160	True	UTF-8 text field