diff --git a/doc/source/rest.rst b/doc/source/rest.rst index 16f66cda2..439febc03 100644 --- a/doc/source/rest.rst +++ b/doc/source/rest.rst @@ -12,6 +12,10 @@ V1 API rest/v1/servers rest/v1/domains rest/v1/records + rest/v1/diagnostics + rest/v1/quotas + rest/v1/reports + rest/v1/sync V2 API ----------------------- diff --git a/doc/source/rest/v1/diagnostics.rst b/doc/source/rest/v1/diagnostics.rst new file mode 100644 index 000000000..a1f59b19c --- /dev/null +++ b/doc/source/rest/v1/diagnostics.rst @@ -0,0 +1,66 @@ +.. + Copyright 2014 Hewlett-Packard Development Company, L.P. + + Author: Endre Karlson + + 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. + + +Diagnostics +=========== + +Overview +-------- + +*Note*: Diagnostics is an extension and needs to be enabled before it can be +used. If Designate returns a 404 error, ensure that the following line has been +added to the designate.conf file:: + + enabled_extensions_v1 = diagnostic, ... + +Diagnose parts of the system. + + +Ping a host on a RPC topic +-------------------------- + +.. http:get:: /diagnostics/ping/(topic)/(host) + + Ping a host on a RPC topic + + **Example request**: + + .. sourcecode:: http + + GET /diagnostics/ping/agents/msdns-1 HTTP/1.1 + Host: example.com + Accept: application/json + Content-Type: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "host": "rpc-hostname", + "status": true, + "backend": "msdns", + "storage": {"status": true, "message": "..."} + } + + :statuscode 200: Success + :statuscode 401: Access Denied \ No newline at end of file diff --git a/doc/source/rest/v1/quotas.rst b/doc/source/rest/v1/quotas.rst new file mode 100644 index 000000000..ffc9b6039 --- /dev/null +++ b/doc/source/rest/v1/quotas.rst @@ -0,0 +1,138 @@ +.. + Copyright 2014 Hewlett-Packard Development Company, L.P. + + Author: Endre Karlson + + 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. + +Quotas +====== + +Overview +-------- +The quotas extension can be used to retrieve a tenant's absolute limits. + +*Note*: Quotas is an extension and needs to be enabled before it can be used. +If Designate returns a 404 error, ensure that the following line has been +added to the designate.conf file:: + + enabled_extensions_v1 = quotas, ... + +Once this line has been added, restart the designate-central and designate-api +services. + +Get Quotas +---------- + +.. http:get:: /quotas/TENANT_ID + + Retrieves quotas for tenant with the specified TENANT_ID. The + following example retrieves the quotas for tenant 12345. + + **Example request:** + + .. sourcecode:: http + + GET /v1/quotas/12345 HTTP/1.1 + Host: 127.0.0.1:9001 + Accept: application/json + Content-Type: application/json + + + **Example response:** + + .. sourcecode:: http + + HTTP/1.1 201 Created + Content-Type: application/json + + { + "domains": 10, + "recordset_records": 20, + "domain_records": 500, + "domain_recordsets": 500 + } + + :form domains: Number of domains the tenant is allowed to own + :form recordset_records: Number of records allowed per recordset + :form domain_records: Number of records allowed per domain + :form domain_recordsets: Number of recordsets allowed per domain + + :statuscode 200: Success + :statuscode 401: Access Denied + +Update Quotas +------------- + +.. http:put:: /quotas/TENANT_ID + + Updates the specified quota(s) to their new values. + + **Example request:** + + .. sourcecode:: http + + PUT /v1/quotas/12345 HTTP/1.1 + Host: 127.0.0.1:9001 + Accept: application/json + Content-Type: application/json + + { + "domains": 1000, + "domain_records": 50 + } + + + **Example response:** + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "domains": 1000, + "recordset_records": 20, + "domain_records": 50, + "domain_recordsets": 500 + } + + :statuscode 200: Success + :statuscode 401: Access Denied + +Reset Quotas to Default +----------------------- + +.. http:delete:: /quotas/TENANT_ID + + Restores the tenant's quotas back to their default values. + + **Example request:** + + .. sourcecode:: http + + DELETE /v1/quotas/12345 HTTP/1.1 + Host: 127.0.0.1:9001 + Accept: application/json + Content-Type: application/json + + + **Example response:** + + .. sourcecode:: http + + HTTP/1.1 200 Success + + :statuscode 200: Success + :statuscode 401: Access Denied + diff --git a/doc/source/rest/v1/reports.rst b/doc/source/rest/v1/reports.rst new file mode 100644 index 000000000..89f0c840d --- /dev/null +++ b/doc/source/rest/v1/reports.rst @@ -0,0 +1,235 @@ +.. + Copyright 2014 Hewlett-Packard Development Company, L.P. + + Author: Endre Karlson + + 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. + + +Reports +======= + +Overview +-------- + +*Note*: Reports is an extension and needs to be enabled before it can be +used. If Designate returns a 404 error, ensure that the following line has been +added to the designate.conf file:: + + enabled_extensions_v1 = reports, ... + +Reports about things in the system + + +Get all tenants +--------------- + +.. http:get:: /reports/tenants + + Fetch all tenants + + **Example request**: + + .. sourcecode:: http + + GET /reports/tenants HTTP/1.1 + Host: example.com + Accept: application/json + Content-Type: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "tenants": ["3d8391080d4a4ec4b3eadf18e6b1539a"] + } + + :form tenants: List of tenants + :statuscode 200: Success + :statuscode 401: Access Denied + +Report tenant resources +----------------------- + +.. http:get:: /reports/(tenant_id) + + Report tenant resources + + **Example request**: + + .. sourcecode:: http + + GET /reports/3d8391080d4a4ec4b3eadf18e6b1539a HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "domain_count": 0, + "domains": [], + "id": "3d8391080d4a4ec4b3eadf18e6b1539a" + } + + :param tenant_id: Tenant Id to get reports for + :type tenant_id: string + :form domain_count: integer + :form domains: Server hostname + :form id: Tenant Id + :statuscode 200: Success + :statuscode 401: Access Denied + +Report resource counts +---------------------- + +.. http:get:: /reports/counts + + Report resource counts + + **Example request**: + + .. sourcecode:: http + + GET /reports/counts HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "domains": 0, + "records": 0, + "tenants": 0 + } + + :form domains: Domains count + :form records: Records count + :form tenants: Tenants count + :statuscode 200: Success + :statuscode 401: Access Denied + +Report tenant counts +---------------------- + +.. http:get:: /reports/counts/tenants + + Report tenant counts + + **Example request**: + + .. sourcecode:: http + + GET /reports/counts/tenants HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "tenants": 0 + } + + + + :form tenants: Tenants count + :statuscode 200: Success + :statuscode 401: Access Denied + +Report domain counts +---------------------- + +.. http:get:: /reports/counts/domains + + Report domain counts + + **Example request**: + + .. sourcecode:: http + + GET /reports/counts/domains HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "domains": 0 + } + + + + :form domains: Domains count + :statuscode 200: Success + :statuscode 401: Access Denied + +Report record counts +---------------------- + +.. http:get:: /reports/counts/records + + Report record counts + + **Example request**: + + .. sourcecode:: http + + GET /reports/counts/records HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "records": 0 + } + + + + :form records: Records count + :statuscode 200: Success + :statuscode 401: Access Denied \ No newline at end of file diff --git a/doc/source/rest/v1/sync.rst b/doc/source/rest/v1/sync.rst new file mode 100644 index 000000000..e7083335a --- /dev/null +++ b/doc/source/rest/v1/sync.rst @@ -0,0 +1,112 @@ +.. + Copyright 2014 Hewlett-Packard Development Company, L.P. + + Author: Endre Karlson + + 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. + + +Synchronize +=========== + +Overview +-------- + +*Note*: Synchronize is an extension and needs to be enabled before it can be +used. If Designate returns a 404 error, ensure that the following line has been +added to the designate.conf file:: + + enabled_extensions_v1 = sync, ... + +Trigger a synchronization of one or more resource(s) in the system. + + +Synchronize all domains +----------------------- + +.. http:post:: /domains/sync + + Synchronize all domains + + **Example request**: + + .. sourcecode:: http + + POST /domains/sync HTTP/1.1 + Host: example.com + Content-Type: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + :statuscode 200: Success + :statuscode 401: Access Denied + + +Synchronize one domain +---------------------- + +.. http:post:: /domains/(uuid:domain_id)/sync + + Synchronize one domain + + **Example request**: + + .. sourcecode:: http + + POST /domains/1dd7851a-74e7-4ddb-b6e8-38a610956bd5/sync HTTP/1.1 + Host: example.com + Content-Type: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + :statuscode 200: Success + :statuscode 401: Access Denied + + +Synchronize one record +---------------------- + +.. http:post:: /domains/(uuid:domain_id)/records/(uuid:record_id)/sync + + Synchronize one record + + **Example request**: + + .. sourcecode:: http + + POST /domains/1dd7851a-74e7-4ddb-b6e8-38a610956bd5/records/1dd7851a-74e7-4ddb-b6e8-38a610956bd5/sync HTTP/1.1 + Host: example.com + Content-Type: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + :statuscode 200: Success + :statuscode 401: Access Denied \ No newline at end of file