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
This commit is contained in:
Michael Johnson
parent
d05232fc07
commit
39652d7a51
23
api-ref/source/dns-api-v2-index.rst
Normal file
23
api-ref/source/dns-api-v2-index.rst
Normal file
@ -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
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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"
|
||||
}]
|
||||
}
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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'
|
||||
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user