Blacklists API Documentation

Create documentation for the Blacklists API

Change-Id: Ia1f7126a5d83602ec5d2126564bbb76b16b6cfc2
Implements:blueprint blacklist-docs

3 files changed, 303 insertions, 8 deletions

diff --git a/doc/source/rest.rst b/doc/source/rest.rst
index 4c40ac56..0d19d534 100644
--- a/doc/source/rest.rst
+++ b/doc/source/rest.rst
@@ -1,5 +1,5 @@
-REST API Documenation
-=====================
+REST API Documentation
+======================
 
 The API has 2 versions - V1 and V2.
 
@@ -21,3 +21,4 @@ V2 API
 
        rest/v2/zones
        rest/v2/tlds
+       rest/v2/blacklists
diff --git a/doc/source/rest/v2/blacklists.rst b/doc/source/rest/v2/blacklists.rst
new file mode 100644
index 00000000..a61a0cb4
--- /dev/null
+++ b/doc/source/rest/v2/blacklists.rst
@@ -0,0 +1,294 @@
+..
+    Copyright (c) 2014 Rackspace Hosting
+    All Rights Reserved.
+
+    Author: Betsy Luzader <betsy.luzader@rackspace.com>
+
+       Licensed under the Apache License, Version 2.0 (the "License"); you may
+       not use this file except in compliance with the License. You may obtain
+       a copy of the License at
+
+            http://www.apache.org/licenses/LICENSE-2.0
+
+       Unless required by applicable law or agreed to in writing, software
+       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+       License for the specific language governing permissions and limitations
+       under the License.
+
+Blacklists
+==========
+
+Overview
+-------------------
+The blacklist entries are used to manage blacklisted zones. If a zone is blacklisted, then it cannot be used to
+create a zone. By default, only an admin can manage these entries. Blacklisted zones are stored as a regular expression
+(regex) pattern in the :ref:`database` in the *blacklists* table.
+
+Blacklist Checks
+-------------------
+Every time a new zone is created, that domain name is checked against the blacklisted zones in the database.
+If it matches the regex pattern, then a 400 is returned with the message "Blacklisted domain name". If there
+is no match, then the zone is created. When a new blacklisted pattern is added, it will catch any matching
+new zones, but it does not check for existing zones that match the blacklisted pattern.
+
+Regular Expressions
+-------------------
+Any valid regular expression may be added to the blacklists table. Here are some examples:
+
+#. ``^example\\.com\\.$``
+    This will block the "example.com." domain, but will not block any sub-domains, e.g. "my.example.com." or anything
+    else containing example.com, such as, "myexample.com."
+
+#. ``^([A-Za-z0-9_\-]+\\.)*example\\.com\\.$``
+    This will block "example.com." and all sub-domains, e.g. "my.example.com.", but anything else containing
+    example.com, will not be blocked, such as, "myexample.com."
+
+*NOTE:* When using regular expressions in json, the '\\' character needs to be escaped with an additional '\\', so it
+needs to be written as "^example\\\\.com\\\\.$"
+
+Create a Blacklist
+------------------
+
+.. http:post:: /blacklists
+
+   Create a blacklist. *pattern* is the only entry that is required. The domain name part of the pattern
+   should end in a period (.).'
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /blacklists HTTP/1.1
+      Host: example.com
+      Accept: application/json
+      Content-Type: application/json
+
+      {
+        "blacklist" : {
+          "pattern" : "^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
+          "description" : "This is a blacklisted domain."
+        }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 201 Created
+      Content-Type: application/json; charset=UTF-8
+      Location: 127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd
+
+    {
+      "blacklist":{
+        "description":"This is a blacklisted domain.",
+        "links":{
+          "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
+      },
+        "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
+        "created_at":"2014-03-11T21:54:57.000000",
+        "updated_at":null,
+        "id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
+      }
+    }
+
+   :form created_at: timestamp
+   :form updated_at: timestamp
+   :form pattern: blacklist regular expression
+   :form id: uuid
+   :form description: UTF-8 text field
+   :form links: links to traverse the list
+   :statuscode 201: Created
+   :statuscode 401: Access Denied
+   :statuscode 400: Invalid Object
+   :statuscode 409: Duplicate Blacklist
+
+Get a Blacklist
+---------------
+
+.. http:get:: /blacklists/(uuid:id)
+
+   Lists a particular Blacklisted domain
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
+      Host: example.com
+      Accept: application/json
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json; charset=UTF-8
+
+      {
+        "blacklist":{
+          "description":"This is a blacklisted domain.",
+          "links":{
+            "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
+          },
+          "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
+          "created_at":"2014-03-11T21:54:57.000000",
+          "updated_at":null,
+          "id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
+        }
+      }
+
+   :form created_at: timestamp
+   :form updated_at: timestamp
+   :form pattern: blacklist regular expression
+   :form id: uuid
+   :form description: UTF-8 text field
+   :form links: links to traverse the list
+   :statuscode 200: OK
+   :statuscode 401: Access Denied
+   :statuscode 404: Blacklist not found
+
+List Blacklists
+---------------
+
+.. http:get:: /blacklists
+
+   Lists all blacklists
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /blacklists HTTP/1.1
+      Host: example.com
+      Accept: application/json
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json; charset=UTF-8
+
+      {
+        "blacklists":[
+          {
+          "description": "This is a blacklisted domain.",
+          "links":{
+            "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
+          },
+          "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
+          "created_at":"2014-03-11T21:54:57.000000",
+          "updated_at":null,
+          "id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
+          },
+          {
+            "description": null,
+            "links":{
+              "self":"http://127.0.0.1:9001/v2/blacklists/61140aff-e2c8-488b-9bf4-da710ec8732b"
+            },
+            "pattern" : "^examples\\.com\\.$",
+            "created_at":"2014-03-07T21:05:59.000000",
+            "updated_at":null,
+            "id":"61140aff-e2c8-488b-9bf4-da710ec8732b"
+          }
+        ],
+        "links":{
+          "self":"http://127.0.0.1:9001/v2/blacklists"
+        }
+      }
+
+   :form created_at: timestamp
+   :form updated_at: timestamp
+   :form pattern: blacklist regular expression
+   :form id: uuid
+   :form description: UTF-8 text field
+   :form links: links to traverse the list
+   :statuscode 200: OK
+   :statuscode 401: Access Denied
+
+Update a Blacklist
+------------------
+
+.. http:patch:: /blacklists/(uuid:id)
+
+   updates a blacklist
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      PATCH blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
+      Host: example.com
+      Accept: application/json
+      Content-Type: application/json
+
+      {
+        "blacklist" : {
+          "pattern" : "^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
+          "description" : "Updated the description"
+        }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json; charset=UTF-8
+
+      {
+        "blacklist":{
+          "description":"Updated the pattern to catch subdomains",
+          "links":{
+            "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
+          },
+          "created_at":"2014-03-11T21:54:57.000000",
+          "updated_at":"2014-03-13T16:49:32.117187",
+          "id":"c47229fb-0831-4b55-a5b5-380d361be4bd",
+          "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$"
+        }
+      }
+
+   :form created_at: timestamp
+   :form updated_at: timestamp
+   :form pattern: blacklist regular expression pattern
+   :form id: uuid
+   :form description: UTF-8 text field
+   :form links: links to traverse the list
+   :statuscode 200: OK
+   :statuscode 401: Access Denied
+   :statuscode 404: Blacklist not found
+   :statuscode 409: Duplicate Blacklist
+
+Delete a Blacklist
+------------------
+
+.. http:delete:: /blacklists/(uuid:id)
+
+   delete a blacklist
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      DELETE /blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
+      Host: example.com
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 204 No Content
+      Content-Type: application/json; charset=UTF-8
+      Content-Length: 0
+
+   :statuscode 204: No Content
+   :statuscode 401: Access Denied
+   :statuscode 404: Blacklist not found
+
+
+
+
+
+
diff --git a/doc/source/rest/v2/tlds.rst b/doc/source/rest/v2/tlds.rst
index c1fbf5e5..27106001 100644
--- a/doc/source/rest/v2/tlds.rst
+++ b/doc/source/rest/v2/tlds.rst
@@ -57,7 +57,7 @@ Create Tld
       {
         "tld" : {
           "name" : "com",
-          "description" : "Tld entry obtained from http://data.iana.org/TLD/tlds-alpha-by-domain.txt"
+          "description" : "Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt"
         }
       }
 
@@ -71,7 +71,7 @@ Create Tld
 
       {
         "tld":{
-          "description":"Tld entry obtained from http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
+          "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"
           },
@@ -118,7 +118,7 @@ Get a Tld
 
       {
         "tld":{
-          "description":"Tld entry obtained from http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
+          "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"
           },
@@ -164,7 +164,7 @@ List Tlds
       {
         "tlds":[
           {
-            "description":"Tld entry obtained from http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
+            "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"
             },
@@ -174,7 +174,7 @@ List Tlds
             "name":"com"
           },
           {
-            "description":"Tld entry obtained from http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
+            "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"
             },
@@ -201,7 +201,7 @@ List Tlds
 Update a Tld
 ---------------
 
-.. http:put:: /tlds/(uuid:id)
+.. http:patch:: /tlds/(uuid:id)
 
    updates a tld