From 852e95eed4aff790dc85dce8b234e4b351c49494 Mon Sep 17 00:00:00 2001 From: Vinod Mangalpally Date: Wed, 29 Jan 2014 13:57:33 -0600 Subject: [PATCH] Add TLD Api documentation Added TLD Api documentation. I also restructured the api documentation as V1 and V2. Closes-Bug: #1271989 Change-Id: I53d33bc84726b58490f879225f6d8e09583c9cd6 --- doc/source/rest.rst | 23 ++- doc/source/rest/{ => v1}/domains.rst | 0 doc/source/rest/{ => v1}/records.rst | 0 doc/source/rest/{ => v1}/servers.rst | 0 doc/source/rest/v2/tlds.rst | 279 +++++++++++++++++++++++++++ 5 files changed, 295 insertions(+), 7 deletions(-) rename doc/source/rest/{ => v1}/domains.rst (100%) rename doc/source/rest/{ => v1}/records.rst (100%) rename doc/source/rest/{ => v1}/servers.rst (100%) create mode 100644 doc/source/rest/v2/tlds.rst diff --git a/doc/source/rest.rst b/doc/source/rest.rst index c5fdef3aa..fcb07f65f 100644 --- a/doc/source/rest.rst +++ b/doc/source/rest.rst @@ -1,13 +1,22 @@ REST API Documenation ===================== -Contents: +The API has 2 versions - V1 and V2. -.. toctree:: - :maxdepth: 2 - :glob: +V1 API +----------------------- + .. toctree:: + :maxdepth: 2 + :glob: - rest/servers - rest/domains - rest/records + rest/v1/servers + rest/v1/domains + rest/v1/records +V2 API +----------------------- + .. toctree:: + :maxdepth: 2 + :glob: + + rest/v2/tlds diff --git a/doc/source/rest/domains.rst b/doc/source/rest/v1/domains.rst similarity index 100% rename from doc/source/rest/domains.rst rename to doc/source/rest/v1/domains.rst diff --git a/doc/source/rest/records.rst b/doc/source/rest/v1/records.rst similarity index 100% rename from doc/source/rest/records.rst rename to doc/source/rest/v1/records.rst diff --git a/doc/source/rest/servers.rst b/doc/source/rest/v1/servers.rst similarity index 100% rename from doc/source/rest/servers.rst rename to doc/source/rest/v1/servers.rst diff --git a/doc/source/rest/v2/tlds.rst b/doc/source/rest/v2/tlds.rst new file mode 100644 index 000000000..c1fbf5e5d --- /dev/null +++ b/doc/source/rest/v2/tlds.rst @@ -0,0 +1,279 @@ +.. + Copyright (c) 2014 Rackspace Hosting + All Rights Reserved. + + 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. + +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 :ref:`database` +in the table *tlds* and are not propagated to the :ref:`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. + +#. 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. + +#. 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 +------------- + +.. http:post:: /tlds + + Create a tld. *name* is the only entry that is required. The *name* should + not end in a period (.). + + **Example request**: + + .. sourcecode:: http + + POST /tlds HTTP/1.1 + Host: example.com + Accept: application/json + Content-Type: application/json + + { + "tld" : { + "name" : "com", + "description" : "Tld entry obtained from http://data.iana.org/TLD/tlds-alpha-by-domain.txt" + } + } + + **Example response**: + + .. sourcecode:: http + + 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 + + { + "tld":{ + "description":"Tld entry obtained from 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 created_at: timestamp + :form updated_at: timestamp + :form name: tld name + :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 Tld + +Get a Tld +------------- + +.. http:get:: /tlds/(uuid:id) + + Lists a particular Tld + + **Example request**: + + .. sourcecode:: http + + GET /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 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 + + { + "tld":{ + "description":"Tld entry obtained from 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 created_at: timestamp + :form updated_at: timestamp + :form name: tld name + :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: Tld not found + +List Tlds +------------ + +.. http:get:: /tlds + + Lists all tlds + + **Example request**: + + .. sourcecode:: http + + GET /tlds 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 + + { + "tlds":[ + { + "description":"Tld entry obtained from 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 entry obtained from 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 created_at: timestamp + :form updated_at: timestamp + :form name: tld name + :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 Tld +--------------- + +.. http:put:: /tlds/(uuid:id) + + updates a tld + + **Example request**: + + .. sourcecode:: http + + PATCH /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1 + Host: example.com + Accept: application/json + Content-Type: application/json + + { + "tld" : { + "name" : "org", + "description" : "Updated the name from com to org" + } + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json; charset=UTF-8 + + { + "tld":{ + "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 created_at: timestamp + :form updated_at: timestamp + :form name: tld name + :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: Tld not found + :statuscode 409: Duplicate Tld + +Delete a Tld +--------------- + +.. http:delete:: /tlds/(uuid:id) + + delete a tld + + **Example request**: + + .. sourcecode:: http + + DELETE /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 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: Tld not found