From 39652d7a518c7b26cc878cbb23b34f94ef8a1252 Mon Sep 17 00:00:00 2001 From: Michael Johnson Date: Wed, 29 Jun 2022 22:39:38 +0000 Subject: [PATCH] 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 | 23 ++++ api-ref/source/dns-api-v2-version.inc | 47 -------- api-ref/source/index.rst | 108 +++++++++++++++--- api-ref/source/parameters.yaml | 30 ++++- .../versions/get-versions-response.json | 37 +++--- designate/api/versions.py | 40 ++++--- designate/common/constants.py | 7 ++ .../Add-API-versioning-f5747a0bc766fb14.yaml | 7 ++ 8 files changed, 201 insertions(+), 98 deletions(-) create mode 100644 api-ref/source/dns-api-v2-index.rst delete mode 100644 api-ref/source/dns-api-v2-version.inc create mode 100644 releasenotes/notes/Add-API-versioning-f5747a0bc766fb14.yaml 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 000000000..0bce803fa --- /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 b4c9de1ff..000000000 --- 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 023b0e219..abc762cf2 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` + +**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 `__. .. 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 27332001c..421f376eb 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 f490a02d4..c69b6c559 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 56854eeb2..cd47dbbdb 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' - 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' - } - ] - }] - } - }) + 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': versions}) return app diff --git a/designate/common/constants.py b/designate/common/constants.py index 1479cf7f6..cf837271e 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 000000000..6c4f3758d --- /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.