76d27ad25c
Also add warnings on the different use of "description" fields in API V1 VS V2 Change-Id: Ie02fe85133d083570d7b6633fdaa84614c77f78a Closes-Bug: 1466568
104 lines
2.3 KiB
ReStructuredText
104 lines
2.3 KiB
ReStructuredText
.. _rest:
|
|
|
|
========================
|
|
REST API Documentation
|
|
========================
|
|
|
|
Intro
|
|
=====
|
|
|
|
In the REST API examples, HTTP requests are defined as raw HTTP. For
|
|
example:
|
|
|
|
.. code-block:: http
|
|
|
|
POST /v2/pools HTTP/1.1 # The HTTP Method, Path and HTTP Version
|
|
Accept: application/json # Headers
|
|
Content-Type: application/json
|
|
|
|
{ # The rest is the body of request
|
|
"name": "Example Pool",
|
|
"ns_records": [
|
|
{
|
|
"hostname": "ns1.example.org.",
|
|
"priority": 1
|
|
}
|
|
]
|
|
}
|
|
|
|
With this info we can make this request using the cURL_ tool. We'll
|
|
assume we are running Designate on `localhost`.
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -X POST -i \
|
|
-H 'Accept: application/json' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"name": "ns1.example.org."}' \
|
|
http://localhost:9001/v1/servers
|
|
|
|
The `-i` flag is used to dump the response headers as well as the
|
|
response body.
|
|
|
|
The cURL tool is extremely robust. Please take a look at the `cURL
|
|
tutorial`_ for more info.
|
|
|
|
.. _cURL: http://curl.haxx.se/
|
|
.. _cURL tutorial: http://curl.haxx.se/docs/manual.html
|
|
|
|
HTTP Headers
|
|
============
|
|
|
|
These headers work for all APIs
|
|
|
|
* X-Designate-Edit-Managed-Records
|
|
- Allows admins (or users with the right role) to modify managed records (records created by designate-sink / reverse floating ip API)
|
|
* X-Auth-All-Projects
|
|
- Allows admins (or users with the right role) to view and edit zones / recordsets for all tenants
|
|
* X-Auth-Sudo-Tenant-ID / X-Auth-Sudo-Project-ID
|
|
- Allows admins (or users with the right role) to impersonate another tenant specified by this header
|
|
|
|
API Versions
|
|
============
|
|
|
|
The API has 2 versions - V1 and V2.
|
|
|
|
.. note:: V1 has been deprecated since the Kilo release.
|
|
|
|
V1 API
|
|
------
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
:glob:
|
|
|
|
rest/v1/servers
|
|
rest/v1/domains
|
|
rest/v1/records
|
|
rest/v1/diagnostics
|
|
rest/v1/quotas
|
|
rest/v1/reports
|
|
rest/v1/sync
|
|
|
|
V2 API
|
|
------
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
:glob:
|
|
|
|
rest/v2/collections
|
|
rest/v2/zones
|
|
rest/v2/recordsets
|
|
rest/v2/tlds
|
|
rest/v2/blacklists
|
|
rest/v2/pools
|
|
|
|
Admin API
|
|
---------
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
:glob:
|
|
|
|
rest/admin/quotas
|
|
rest/admin/zones
|
|
|