Add simple API versioning to the Designate API

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.
Updates the version discovery document to be compliant with OpenStack
version discovery.
Restructures the API reference to provide more information about the
versioning.

Depends-On: https://review.opendev.org/c/openstack/designate-tempest-plugin/+/848323
Change-Id: I13162711b521472ec8b796ced34d0b7107aaed36

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.