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:
Vinod Mangalpally
parent
4db7981acd
commit
852e95eed4
@ -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
|
||||
|
||||
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