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

8 files changed, 201 insertions, 98 deletions

diff --git a/api-ref/source/dns-api-v2-index.rst b/api-ref/source/dns-api-v2-index.rst
new file mode 100644
index 00000000..0bce803f
--- /dev/null
+++ b/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
diff --git a/api-ref/source/dns-api-v2-version.inc b/api-ref/source/dns-api-v2-version.inc
deleted file mode 100644
index b4c9de1f..00000000
--- a/api-ref/source/dns-api-v2-version.inc
+++ /dev/null
@@ -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
-
-
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index 023b0e21..abc762cf 100644
--- a/api-ref/source/index.rst
+++ b/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
-.. 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 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
+   - 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.
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 27332001..421f376e 100644
--- a/api-ref/source/parameters.yaml
+++ b/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:
diff --git a/api-ref/source/samples/versions/get-versions-response.json b/api-ref/source/samples/versions/get-versions-response.json
index f490a02d..c69b6c55 100644
--- a/api-ref/source/samples/versions/get-versions-response.json
+++ b/api-ref/source/samples/versions/get-versions-response.json
@@ -1,16 +1,25 @@
 {
-    "versions": {
-        "values": [
-            {
-                "id": "v2",
-                "links": [
-                    {
-                        "href": "http://127.0.0.1:9001/v2",
-                        "rel": "self"
-                    }
-                ],
-                "status": "CURRENT"
-            }
-        ]
-    }
+  "versions": [{
+    "id": "v2",
+    "links": [{
+      "href": "http://198.51.100.88/dns/v2",
+      "rel": "self"
+    }, {
+      "href": "https://docs.openstack.org/api-ref/dns",
+      "rel": "help"
+    }],
+    "status": "SUPPORTED",
+    "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"
+  }]
 }
diff --git a/designate/api/versions.py b/designate/api/versions.py
index 56854eeb..cd47dbbd 100644
--- a/designate/api/versions.py
+++ b/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'
+
+        versions = []
+        # Initial API version for v2 API
+        _add_a_version(versions, 'v2', api_url, constants.SUPPORTED,
+                       '2022-06-29T00:00:00Z')
+        _add_a_version(versions, 'v2.0', api_url, constants.CURRENT,
+                       '2022-06-29T00:00:00Z')
 
-        return flask.jsonify({
-            "versions": {
-                "values": [{
-                    'id': 'v2',
-                    'status': 'CURRENT',
-                    'links': [
-                        {
-                            'href': url_root.rstrip('/') + '/v2',
-                            'rel': 'self',
-                        }, {
-                            'rel': 'help',
-                            'href': 'https://docs.openstack.org/api-ref/dns'
-                        }
-                    ]
-                }]
-            }
-        })
+        return flask.jsonify({'versions': versions})
 
     return app
diff --git a/designate/common/constants.py b/designate/common/constants.py
index 1479cf7f..cf837271 100644
--- a/designate/common/constants.py
+++ b/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'
diff --git a/releasenotes/notes/Add-API-versioning-f5747a0bc766fb14.yaml b/releasenotes/notes/Add-API-versioning-f5747a0bc766fb14.yaml
new file mode 100644
index 00000000..6c4f3758
--- /dev/null
+++ b/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.