Merge "Add v1 missing api docs"

5 files changed, 555 insertions, 0 deletions

diff --git a/doc/source/rest.rst b/doc/source/rest.rst
index 16f66cda..439febc0 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 00000000..a1f59b19
--- /dev/null
+++ b/doc/source/rest/v1/diagnostics.rst
@@ -0,0 +1,66 @@
+..
+    Copyright 2014 Hewlett-Packard Development Company, L.P.
+
+    Author: Endre Karlson <endre.karlson@hp.com>
+
+    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 00000000..ffc9b603
--- /dev/null
+++ b/doc/source/rest/v1/quotas.rst
@@ -0,0 +1,138 @@
+..
+    Copyright 2014 Hewlett-Packard Development Company, L.P.
+
+    Author: Endre Karlson <endre.karlson@hp.com>
+
+    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 00000000..89f0c840
--- /dev/null
+++ b/doc/source/rest/v1/reports.rst
@@ -0,0 +1,235 @@
+..
+    Copyright 2014 Hewlett-Packard Development Company, L.P.
+
+    Author: Endre Karlson <endre.karlson@hp.com>
+
+    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 00000000..e7083335
--- /dev/null
+++ b/doc/source/rest/v1/sync.rst
@@ -0,0 +1,112 @@
+..
+    Copyright 2014 Hewlett-Packard Development Company, L.P.
+
+    Author: Endre Karlson <endre.karlson@hp.com>
+
+    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