Add Recordset to api-ref docs

Change-Id: I727ef393cf5a730b701f7212c59842d5262172ad

api-ref/source/dns-api-v2-recordset.inc

@@ -0,0 +1,358 @@
+==========
+Recordsets
+==========
+
+Recordsets operations.
+
+
+Create Recordset
+================
+
+.. rest_method::  POST /v2/zones/{zone_id}/recordsets
+
+Create a recordset in a zone
+
+
+Normal response codes: 200
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: path_zone_id
+   - ttl: recordset_ttl
+   - description: recordset_description
+   - type: recordset_type
+   - records: recordset_records
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/recordsets/create-recordset-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - project_id: project_id
+   - name: recordset_name
+   - ttl: recordset_ttl
+   - status: status
+   - action: action
+   - zone_id: recordset_zone_id
+   - zone_name: recordset_zone_name
+   - description: recordset_description
+   - type: recordset_type
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/recordsets/create-recordset-response.json
+   :language: javascript
+
+
+List Recordsets in a Zone
+=========================
+
+.. rest_method::  GET /v2/zones/{zone_id}/recordsets
+
+This lists all recordsets in a zone
+
+
+Normal response codes: 200
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: path_zone_id
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
+   - name: recordset_name_filter
+   - type: recordset_type_filter
+   - ttl: recordset_ttl_filter
+   - data: recordset_data_filter
+   - status: recordset_status_filter
+   - description: recordset_description_filter
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - project_id: project_id
+   - name: recordset_name
+   - ttl: recordset_ttl
+   - status: status
+   - action: action
+   - zone_id: recordset_zone_id
+   - zone_name: recordset_zone_name
+   - description: recordset_description
+   - type: recordset_type
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+   - metadata: metadata
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/recordsets/list-recordset-in-zone-response.json
+   :language: javascript
+
+
+List all Recordsets owned by project
+====================================
+
+.. rest_method::  GET /v2/recordsets
+
+This lists all recordsets owned by a project in Designate
+
+Normal response codes: 200
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: path_zone_id
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
+   - name: recordset_name_filter
+   - type: recordset_type_filter
+   - ttl: recordset_ttl_filter
+   - data: recordset_data_filter
+   - status: recordset_status_filter
+   - description: recordset_description_filter
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - project_id: project_id
+   - name: recordset_name
+   - ttl: recordset_ttl
+   - status: status
+   - action: action
+   - zone_id: recordset_zone_id
+   - zone_name: recordset_zone_name
+   - description: recordset_description
+   - type: recordset_type
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+   - metadata: metadata
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/recordsets/list-all-recordset-response.json
+   :language: javascript
+
+
+Show a Recordset
+================
+
+.. rest_method::  GET /v2/recordsets/{zone_id}/{recordset_id}
+
+Show an single recordset
+
+Normal response codes: 200
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: path_zone_id
+   - recordset_id: path_recordset_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - project_id: project_id
+   - name: recordset_name
+   - ttl: recordset_ttl
+   - status: status
+   - action: action
+   - zone_id: recordset_zone_id
+   - zone_name: recordset_zone_name
+   - description: recordset_description
+   - type: recordset_type
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/recordsets/show-recordset-response.json
+   :language: javascript
+
+
+Update a Recordset
+==================
+
+.. rest_method::  PATCH /v2/zone/{zone_id}/recordsets/{recordset_id}
+
+Update a recordset
+
+Normal response codes: 201
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: path_zone_id
+   - recordset_id: path_recordset_id
+   - ttl: recordset_ttl
+   - description: recordset_description
+   - records: recordset_records
+
+Request Example
+---------------
+
+.. literalinclude:: samples/recordsets/update-recordset-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - project_id: project_id
+   - name: recordset_name
+   - ttl: recordset_ttl
+   - status: status
+   - action: action
+   - zone_id: recordset_zone_id
+   - zone_name: recordset_zone_name
+   - description: recordset_description
+   - type: recordset_type
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/recordsets/update-recordset-response.json
+   :language: javascript
+
+
+Delete a Recordset
+==================
+
+.. rest_method::  DELETE /v2/zone/{zone_id}/recordsets/{recordset_id}
+
+Delete a recordset
+
+Normal response codes: 201
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: path_zone_id
+   - recordset_id: path_recordset_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - project_id: project_id
+   - name: recordset_name
+   - ttl: recordset_ttl
+   - status: status
+   - action: action
+   - zone_id: recordset_zone_id
+   - zone_name: recordset_zone_name
+   - description: recordset_description
+   - type: recordset_type
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/recordsets/update-recordset-response.json
+   :language: javascript
+

api-ref/source/dns-api-v2-zone.inc

@@ -95,6 +95,12 @@ Request
    - marker: marker
    - sort_dir: sort_dir
    - sort_key: sort_key
+   - name: zone_name_filter
+   - type: zone_type_filter
+   - email: zone_email_filter
+   - status: zone_status_filter
+   - description: zone_description_filter
+   - ttl: zone_ttl_filter
 
 
 Response Parameters
@@ -120,7 +126,7 @@ Response Parameters
    - created_at: created_at
    - updated_at: updated_at
    - links: links
-
+   - metadata: metadata
 
 
 Response Example
@@ -150,7 +156,8 @@ Request
    - x-auth-token: x-auth-token
    - x-auth-all-projects: x-auth-all-projects
    - x-auth-sudo-project-id: x-auth-sudo-project-id
-   - zone_id: zone_id
+   - zone_id: path_zone_id
+
 
 
 Response Parameters
@@ -206,7 +213,7 @@ Request
    - x-auth-token: x-auth-token
    - x-auth-all-projects: x-auth-all-projects
    - x-auth-sudo-project-id: x-auth-sudo-project-id
-   - zone_id: zone_id
+   - zone_id: path_zone_id
    - email: zone_email_update
    - ttl: zone_ttl
    - description: zone_description
@@ -272,7 +279,7 @@ Request
    - x-auth-token: x-auth-token
    - x-auth-all-projects: x-auth-all-projects
    - x-auth-sudo-project-id: x-auth-sudo-project-id
-   - zone_id: zone_id
+   - zone_id: path_zone_id
 
 
 Response Parameters

api-ref/source/index.rst

@@ -7,3 +7,4 @@
 .. rest_expand_all::
 
 .. include:: dns-api-v2-zone.inc
+.. include:: dns-api-v2-recordset.inc

api-ref/source/parameters.yaml

@@ -43,6 +43,19 @@ x-openstack-request-id:
 # Path Variables
 #################
 
+path_zone_id:
+  description: |
+    ID for the zone
+  in: path
+  required: true
+  type: uuid
+
+path_recordset_id:
+  description: |
+    ID for the recordset
+  in: path
+  required: true
+  type: uuid
 
 # Query Variables
 ##################
@@ -154,7 +167,16 @@ action:
 
 links:
   description: |
-    Links to the resource, and other related resources
+    Links to the resource, and other related resources.
+    When a response has been broken into pages, we will include
+    a ``next`` link that should be followed to retrive all results
+  in: body
+  required: true
+  type: object
+
+metadata:
+  description: |
+    Returns the ``total_count`` of resources matching this filter
   in: body
   required: true
   type: object
@@ -170,17 +192,54 @@ links:
 # Path Variables
 #################
 
-zone_id:
-  description: |
-    ID for the zone
-  in: path
-  required: true
-  type: string
-
-
 # Query Variables
 ##################
 
+# Filters
+# 'name', 'type', 'email', 'status', 'description', 'ttl'
+
+zone_name_filter:
+  description: |
+    Filter results to only show zones that have a name matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_type_filter:
+  description: |
+    Filter results to only show zones that have a type matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_email_filter:
+  description: |
+    Filter results to only show zones that have an email matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_status_filter:
+  description: |
+    Filter results to only show zones that have a status matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_description_filter:
+  description: |
+    Filter results to only show zones that have a description matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_ttl_filter:
+  description: |
+    Filter results to only show zones that have a ttl matching the filter
+  in: query
+  required: false
+  type: integer
+
 # Body Variables
 #################
 
@@ -263,6 +322,118 @@ zone_transfered_at:
   type: enum
 
 
+#############################
+#    Recordset Variables    #
+#############################
+
+
+# Header Variables
+###################
+
+# Path Variables
+#################
+
+# Query Variables
+##################
+
+# Filters
+# 'name', 'type', 'ttl', 'data', 'status', 'description'
+
+recordset_name_filter:
+  description: |
+    Filter results to only show recordsets that have a name matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_type_filter:
+  description: |
+    Filter results to only show recordsets that have a type matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_ttl_filter:
+  description: |
+    Filter results to only show recordsets that have a ttl matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_data_filter:
+  description: |
+    Filter results to only show recordsets that have a record with data matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_status_filter:
+  description: |
+    Filter results to only show recordsets that have a status matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_description_filter:
+  description: |
+    Filter results to only show recordsets that have a description matching the filter
+  in: query
+  required: false
+  type: string
+
+# Body Variables
+#################
+
+recordset_name:
+  description: |
+    DNS Name for the recordset
+  in: body
+  required: true
+  type: hostname
+
+recordset_zone_id:
+  description: |
+    ID for the zone that contains this recordset
+  in: body
+  required: true
+  type: uuid
+
+recordset_zone_name:
+  description: |
+    The name of the zone that contains this recordset
+  in: body
+  required: true
+  type: string
+
+recordset_ttl:
+  description: |
+    TTL (Time to Live) for the recordset.
+  in: body
+  required: false
+  type: integer
+
+recordset_type:
+  description: |
+    They RRTYPE of the recordset.
+  in: body
+  required: true
+  type: string
+
+recordset_records:
+  description: |
+    A list of data for this recordset. Each item will be a separate record in Designate
+    These items should conform to the DNS spec for the record type - e.g. A records
+    must be IPv4 addresses, CNAME records must be a hostname.
+  in: body
+  required: true
+  type: string
+
+recordset_description:
+  description: |
+    Description for this recordset
+  in: body
+  required: false
+  type: string
 
 #############################
 #      <ITEM> Variables       #

api-ref/source/samples/recordsets/create-recordset-request.json

@@ -0,0 +1,9 @@
+{
+  "name" : "example.org.",
+  "description" : "This is an example record set.",
+  "type" : "A",
+  "ttl" : 3600,
+  "records" : [
+      "10.1.0.2"
+  ]
+}

api-ref/source/samples/recordsets/create-recordset-response.json

@@ -0,0 +1,21 @@
+{
+    "description": "This is an example record set.",
+    "links": {
+        "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
+    },
+    "updated_at": null,
+    "records": [
+        "10.1.0.2"
+    ],
+    "ttl": 3600,
+    "id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
+    "name": "example.org.",
+    "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+    "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
+    "zone_name": "example.com.",
+    "created_at": "2014-10-24T19:59:44.000000",
+    "version": 1,
+    "type": "A",
+    "status": "PENDING",
+    "action": "CREATE"
+}

api-ref/source/samples/recordsets/delete-recordset-response.json

@@ -0,0 +1,22 @@
+{
+    "description": "Updated description",
+    "links": {
+        "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
+    },
+    "updated_at": null,
+    "records": [
+        "10.1.0.2",
+        "10.1.0.3",
+    ],
+    "ttl": null,
+    "id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
+    "name": "example.org.",
+    "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+    "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
+    "zone_name": "example.com.",
+    "created_at": "2014-10-24T19:59:44.000000",
+    "version": 2,
+    "type": "A",
+    "status": "PENDING",
+    "action": "DELETE"
+}

api-ref/source/samples/recordsets/list-all-recordset-response.json

@@ -0,0 +1,32 @@
+{
+    "recordsets": [
+        {
+            "description": "This is an example record set.",
+            "links": {
+                "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
+            },
+            "updated_at": null,
+            "records": [
+                "10.1.0.2"
+            ],
+            "ttl": 3600,
+            "id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
+            "name": "example.org.",
+            "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+            "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
+            "zone_name": "example.com.",
+            "created_at": "2014-10-24T19:59:44.000000",
+            "version": 1,
+            "type": "A",
+            "status": "PENDING",
+            "action": "CREATE"
+        }
+    ],
+    "links": {
+        "self": "http://127.0.0.1:9001/v2/recordsets?limit=1",
+        "next": "http://127.0.0.1:9001/v2/recordsets?limit=1&marker=45fd892d-7a67-4f65-9df0-87273f228d6c"
+    },
+    "metadata": {
+        "total_count": 2
+    }
+}

api-ref/source/samples/recordsets/list-recordset-in-zone-response.json

@@ -0,0 +1,32 @@
+{
+    "recordsets": [
+        {
+            "description": "This is an example record set.",
+            "links": {
+                "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
+            },
+            "updated_at": null,
+            "records": [
+                "10.1.0.2"
+            ],
+            "ttl": 3600,
+            "id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
+            "name": "example.org.",
+            "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+            "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
+            "zone_name": "example.com.",
+            "created_at": "2014-10-24T19:59:44.000000",
+            "version": 1,
+            "type": "A",
+            "status": "PENDING",
+            "action": "CREATE"
+        }
+    ],
+    "links": {
+        "self": "http://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets?limit=1",
+        "next": "http://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets?limit=1&marker=45fd892d-7a67-4f65-9df0-87273f228d6c"
+    },
+    "metadata": {
+        "total_count": 2
+    }
+}

api-ref/source/samples/recordsets/show-recordset-response.json

@@ -0,0 +1,21 @@
+{
+    "description": "This is an example record set.",
+    "links": {
+        "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
+    },
+    "updated_at": null,
+    "records": [
+        "10.1.0.2"
+    ],
+    "ttl": 3600,
+    "id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
+    "name": "example.org.",
+    "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+    "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
+    "zone_name": "example.com.",
+    "created_at": "2014-10-24T19:59:44.000000",
+    "version": 1,
+    "type": "A",
+    "status": "ACTIVE",
+    "action": "NONE"
+}

api-ref/source/samples/recordsets/update-recordset-request.json

@@ -0,0 +1,8 @@
+{
+  "description" : "Updated description",
+  "ttl" : null,
+  "records" : [
+      "10.1.0.2",
+      "10.1.0.3"
+  ]
+}

api-ref/source/samples/recordsets/update-recordset-response.json

@@ -0,0 +1,22 @@
+{
+    "description": "Updated description",
+    "links": {
+        "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
+    },
+    "updated_at": null,
+    "records": [
+        "10.1.0.2",
+        "10.1.0.3",
+    ],
+    "ttl": null,
+    "id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
+    "name": "example.org.",
+    "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+    "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
+    "zone_name": "example.com.",
+    "created_at": "2014-10-24T19:59:44.000000",
+    "version": 2,
+    "type": "A",
+    "status": "PENDING",
+    "action": "UPDATE"
+}

api-ref/source/samples/zones/list-zones-response.json

@@ -21,5 +21,12 @@
               "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3"
             }
         }
-    ]
+    ],
+    "links": {
+        "self": "http://127.0.0.1:9001/v2/zones?limit=1",
+        "next": "http://127.0.0.1:9001/v2/zones?limit=1&marker=45fd892d-7a67-4f65-9df0-87273f228d6c"
+    },
+    "metadata": {
+        "total_count": 2
+    }
 }