Designate/Blueprints/Blacklist API

Overview

Gerrit Patch	[]
Launchpad Blueprint	[1]

This blueprint proposes to provide an admin-only API call to dynamically manage blacklisted domains.

Blacklisted domains are domains that Designate will prevent from being used at the TLD level. It does not prevent them from being used as lower level domains. For instance, if google.com is blacklisted, then that would effectively stop someone trying to add the domain www.google.com. However, it would not prohibit google.com.au, so that domain would need to be blacklisted separately, if desired.

Currently, the list of blacklisted domains resides 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 while blacklisted domains are not normally added or changed often, when it is needed, 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.

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

API Resource

One new resource, blacklist will be exposed as part of the Designate API. The blacklist resource will allow authorized users to create a new blacklisted domain.

The blacklist resource provides the following data:

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

API Details: Create / List / Delete Instance

Verb	Resource	Description
GET	/blacklist	Returns the list of blacklisted domains
GET	/blacklist/{id}	Returns a specific blacklisted domain
POST	/blacklist	Creates a new blacklisted domain based on the parameters supplied in the request body
PUT	/blacklist/{id}	Returns the specific blacklisted domain that was updated
DELETE	/blacklist/{id}	Delete the blacklisted domain. No message body is expected in the request

Get Blacklisted Domains (GET)

When no id is specified all blacklisted domains are returned. If a domain is specified in the URL, then only that specific blacklisted domain is returned.

There is no request message body in either case.

Response

   {
       “blacklist”: [
           {
               “id”: "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
               “pattern”: “google\\.com$”,
               "created_at": "2012-11-02T19:56:26.000000",      
               "updated_at": null
               “description”: null
           },
           {
               “id”: "2e32e609-3a4f-45ba-bdef-e50eacd34521",
               “pattern”: “rackspace\\.com$”,
               “created_at”: “2012-11-02T19:56:26.000000",      
               “updated_at”: null
               “description”: null
             }
         ]
   }

Create a Blacklisted Domain (POST)

When creating a blacklisted domain, the caller must supply a domain name.

Request

   {
       “blacklist”: {
           “pattern”: “google\\.com$”
       }
    }

Response

   {
       “blacklist”: {
           {
              “id”: "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
              “pattern”: “google\\.com$”,
              "created_at": "2012-11-02T19:56:26.000000",      
              "updated_at": null,
              “description”: null
           }
       }
   }

Update a Blacklisted Domain (PUT)

When creating a blacklisted domain, the caller must supply item to be changed.

Request

   {
       “blacklist”: {
           “description”: “This is a comment added.”
       }
    }

Response

   {
       “blacklist”: {
           {
              “id”: "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
              “pattern”: “google\\.com$”,
              "created_at": "2012-11-02T19:56:26.000000",      
              "updated_at": "2013-01-02T17:56:26.000000"
              “description”: "This is a comment added."
           }
       }
   }

Delete a Blacklisted Domain (DELETE)

When deleting a blacklisted domain, 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: blacklist, which will store the blacklisted domain name, along with other data.

Name	Data Type	Length	Nullable	Details
id	VARCHAR	36	False	Primary Key, Generated UUID
pattern	VARCHAR	512	False	Regex pattern of zone to be blacklisted
version	INTEGER	-	False	Designate API version
created_at	DATETIME	-	False	UTC time of creation
updated_at	DATETIME	-	True	UTC time of last update
description	VARCHAR	160	True	UTF-8 text field