Add TLD Api documentation
Added TLD Api documentation. I also restructured the api documentation as V1 and V2. Closes-Bug: #1271989 Change-Id: I53d33bc84726b58490f879225f6d8e09583c9cd6
This commit is contained in:
parent
4db7981acd
commit
852e95eed4
@ -1,13 +1,22 @@
|
|||||||
REST API Documenation
|
REST API Documenation
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
Contents:
|
The API has 2 versions - V1 and V2.
|
||||||
|
|
||||||
.. toctree::
|
V1 API
|
||||||
:maxdepth: 2
|
-----------------------
|
||||||
:glob:
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
:glob:
|
||||||
|
|
||||||
rest/servers
|
rest/v1/servers
|
||||||
rest/domains
|
rest/v1/domains
|
||||||
rest/records
|
rest/v1/records
|
||||||
|
|
||||||
|
V2 API
|
||||||
|
-----------------------
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
rest/v2/tlds
|
||||||
|
279
doc/source/rest/v2/tlds.rst
Normal file
279
doc/source/rest/v2/tlds.rst
Normal file
@ -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
|
Loading…
Reference in New Issue
Block a user