Merge "Add simple API versioning to the Designate API"

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.