Merge "Add simple API versioning to the Designate API"

api-ref/source/dns-api-v2-index.rst

@@ -0,0 +1,23 @@
+:tocdepth: 2
+
+===========
+ DNS v2 API
+===========
+
+.. rest_expand_all::
+
+.. include:: dns-api-v2-zone.inc
+.. include:: dns-api-v2-zone-import.inc
+.. include:: dns-api-v2-zone-export.inc
+.. include:: dns-api-v2-zone-tasks.inc
+.. include:: dns-api-v2-zone-ownership-transfer-request.inc
+.. include:: dns-api-v2-zone-ownership-transfer-accept.inc
+.. include:: dns-api-v2-recordset.inc
+.. include:: dns-api-v2-pool.inc
+.. include:: dns-api-v2-limits.inc
+.. include:: dns-api-v2-tld.inc
+.. include:: dns-api-v2-tsigkey.inc
+.. include:: dns-api-v2-blacklist.inc
+.. include:: dns-api-v2-quota.inc
+.. include:: dns-api-v2-service-status.inc
+.. include:: dns-api-v2-reverse-floatingips.inc

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

@@ -1,47 +0,0 @@
-============
-API Versions
-============
-
-Show all enabled API versions
-
-List all API versions
-=====================
-
-.. rest_method::  GET /
-
-
-.. rest_status_code:: success status.yaml
-
-   - 200
-
-
-.. rest_status_code:: error status.yaml
-
-   - 400
-   - 401
-   - 403
-   - 404
-   - 405
-   - 503
-
-
-Request
--------
-
-No parameters needed
-
-Response Parameters
--------------------
-
-.. rest_parameters:: parameters.yaml
-
-   - x-openstack-request-id: x-openstack-request-id
-
-
-Response Example
-----------------
-
-.. literalinclude:: samples/versions/get-versions-response.json
-   :language: javascript
-
-

api-ref/source/index.rst

@@ -1,24 +1,94 @@
 :tocdepth: 2
 
-========
+==============
- DNS API
+ Designate API
-========
+==============
+
+This is a reference for the OpenStack DNS API which is provided by
+the Designate project.
+
+**Current** API version
+
+    :doc:`Designate API v2<dns-api-v2-index>`
+
+**Supported** API version
+
+    None
+
+.. toctree::
+   :hidden:
+
+   dns-api-v2-index
+
+Designate API minor releases are additive to the API major revision and share
+the same URL path. Minor revision changes to the API are called out in the API
+reference in the section the change occurred in. Subsequent minor versions are
+a superset of the previous versions of the same major revision.
+
+The API status reflects the state of the endpoint on the service.
+
+* *Current* indicates a stable version that is up-to-date, recent, and might
+  receive future versions. This endpoint should be prioritized over all
+  others.
+* *Supported* is a stable version that is available on the server. However, it
+  is not likely the most recent available and might not be updated or might
+  be deprecated at some time in the future.
+* *Deprecated* is a stable version that is still available but is being
+  deprecated and might be removed in the future.
+* *Experimental* is not a stable version. This version is under development or
+  contains features that are otherwise subject to change.
+
+For more information about API status values and version information, see
+`Version Discovery <https://wiki.openstack.org/wiki/VersionDiscovery>`__.
 
 .. rest_expand_all::
 
-.. include:: dns-api-v2-version.inc
+============
-.. include:: dns-api-v2-zone.inc
+API Versions
-.. include:: dns-api-v2-zone-import.inc
+============
-.. include:: dns-api-v2-zone-export.inc
+
-.. include:: dns-api-v2-zone-tasks.inc
+Show all enabled API versions
-.. include:: dns-api-v2-zone-ownership-transfer-request.inc
+
-.. include:: dns-api-v2-zone-ownership-transfer-accept.inc
+List all API versions
-.. include:: dns-api-v2-recordset.inc
+=====================
-.. include:: dns-api-v2-pool.inc
+
-.. include:: dns-api-v2-limits.inc
+.. rest_method::  GET /
-.. include:: dns-api-v2-tld.inc
+
-.. include:: dns-api-v2-tsigkey.inc
+
-.. include:: dns-api-v2-blacklist.inc
+.. rest_status_code:: success status.yaml
-.. include:: dns-api-v2-quota.inc
+
-.. include:: dns-api-v2-service-status.inc
+   - 200
-.. include:: dns-api-v2-reverse-floatingips.inc
+
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 405
+   - 500
+   - 503
+
+
+Request
+-------
+
+No parameters needed
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: api_version_id
+   - links: links
+   - status: api_version_status
+   - updated_at: updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: samples/versions/get-versions-response.json
+   :language: javascript
+
+.. note::
+   This is just an example output and does not represent the current API
+   versions available.

api-ref/source/parameters.yaml

@@ -385,6 +385,34 @@ action:
   required: true
   type: enum
 
+api_links:
+  description: |
+    Links to the resources in question.
+  in: body
+  required: true
+  type: array
+
+api_version_id:
+  description: |
+    A common name for the version.
+  in: body
+  required: true
+  type: string
+
+api_version_status:
+  description: |
+    The status of this API version. This can be one of:
+
+    - ``CURRENT``: This is the preferred version of the API to use.
+    - ``SUPPORTED``: This is an older, but still supported version of the API.
+    - ``DEPRECATED``: A deprecated version of the API that is slated for
+      removal.
+    - ``EXPERIMENTAL``: This version is under development or contains features
+      that are otherwise subject to change or removal.
+  in: body
+  required: true
+  type: string
+
 blacklist_description:
   description: |
     Description for this blacklist
@@ -715,7 +743,7 @@ updated_at:
   description: |
     Date / Time when resource last updated.
   in: body
-  required: false
+  required: true
   type: datestamp
 
 version:

api-ref/source/samples/versions/get-versions-response.json

@@ -1,16 +1,25 @@
 {
-    "versions": {
+  "versions": [{
-        "values": [
+    "id": "v2",
-            {
+    "links": [{
-                "id": "v2",
+      "href": "http://198.51.100.88/dns/v2",
-                "links": [
+      "rel": "self"
-                    {
+    }, {
-                        "href": "http://127.0.0.1:9001/v2",
+      "href": "https://docs.openstack.org/api-ref/dns",
-                        "rel": "self"
+      "rel": "help"
-                    }
+    }],
-                ],
+    "status": "SUPPORTED",
-                "status": "CURRENT"
+    "updated": "2022-06-29T00:00:00Z"
-            }
+  }, {
-        ]
+    "id": "v2.0",
-    }
+    "links": [{
+      "href": "http://198.51.100.88/dns/v2",
+      "rel": "self"
+    }, {
+      "href": "https://docs.openstack.org/api-ref/dns",
+      "rel": "help"
+    }],
+    "status": "CURRENT",
+    "updated": "2022-06-29T00:00:00Z"
+  }]
 }

designate/api/versions.py

@@ -16,9 +16,23 @@
 import flask
 from oslo_config import cfg
 
+from designate.common import constants
+
 cfg.CONF.import_opt('enable_host_header', 'designate.api', group='service:api')
 
 
+def _add_a_version(versions, version, api_url, status, timestamp):
+    versions.append({
+        'id': version,
+        'status': status,
+        'updated': timestamp,
+        'links': [{'href': api_url,
+                   'rel': 'self'},
+                  {'href': constants.API_REF_URL,
+                   'rel': 'help'}]
+    })
+
+
 def factory(global_config, **local_conf):
     app = flask.Flask('designate.api.versions')
 
@@ -28,23 +42,15 @@ def factory(global_config, **local_conf):
             url_root = flask.request.url_root
         else:
             url_root = cfg.CONF['service:api'].api_base_uri
+        api_url = url_root.rstrip('/') + '/v2'
 
-        return flask.jsonify({
+        versions = []
-            "versions": {
+        # Initial API version for v2 API
-                "values": [{
+        _add_a_version(versions, 'v2', api_url, constants.SUPPORTED,
-                    'id': 'v2',
+                       '2022-06-29T00:00:00Z')
-                    'status': 'CURRENT',
+        _add_a_version(versions, 'v2.0', api_url, constants.CURRENT,
-                    'links': [
+                       '2022-06-29T00:00:00Z')
-                        {
+
-                            'href': url_root.rstrip('/') + '/v2',
+        return flask.jsonify({'versions': versions})
-                            'rel': 'self',
-                        }, {
-                            'rel': 'help',
-                            'href': 'https://docs.openstack.org/api-ref/dns'
-                        }
-                    ]
-                }]
-            }
-        })
 
     return app

designate/common/constants.py

@@ -12,6 +12,13 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+# API constants
+API_REF_URL = 'https://docs.openstack.org/api-ref/dns'
+CURRENT = 'CURRENT'
+SUPPORTED = 'SUPPORTED'
+DEPRECATED = 'DEPRECATED'
+EXPERIMENTAL = 'EXPERIMENTAL'
+
 # RBAC related constants
 RBAC_PROJECT_ID = 'project_id'
 RBAC_TARGET_PROJECT_ID = 'target_project_id'

releasenotes/notes/Add-API-versioning-f5747a0bc766fb14.yaml

@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    Adds simple API versioning for Designate. Designate API minor releases are
+    additive to the API major revision and share the same URL path. Subsequent
+    minor versions are a superset of the previous versions of the same major
+    revision.