diff options
| -rw-r--r-- | api-ref/source/dns-api-v2-index.rst | 23 | ||||
| -rw-r--r-- | api-ref/source/dns-api-v2-version.inc | 47 | ||||
| -rw-r--r-- | api-ref/source/index.rst | 108 | ||||
| -rw-r--r-- | api-ref/source/parameters.yaml | 30 | ||||
| -rw-r--r-- | api-ref/source/samples/versions/get-versions-response.json | 37 | ||||
| -rw-r--r-- | designate/api/versions.py | 40 | ||||
| -rw-r--r-- | designate/common/constants.py | 7 | ||||
| -rw-r--r-- | releasenotes/notes/Add-API-versioning-f5747a0bc766fb14.yaml | 7 |
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. |