From f7dcefb554fabe46caafdefcd71cbc10cbc9901d Mon Sep 17 00:00:00 2001 From: licanwei Date: Tue, 4 Dec 2018 18:31:20 +0800 Subject: [PATCH] Add version api ref Change-Id: I93cb484a1f3ae533558ecde0cd79c8b6b2fb18f1 --- api-ref/source/index.rst | 3 +- api-ref/source/parameters.yaml | 65 +++++++++++++++ api-ref/source/samples/api-root-response.json | 30 +++++++ .../source/samples/api-v1-root-response.json | 80 ++++++++++++++++++ api-ref/source/watcher-api-versions.inc | 81 +++++++++++++++++++ 5 files changed, 258 insertions(+), 1 deletion(-) create mode 100644 api-ref/source/samples/api-root-response.json create mode 100644 api-ref/source/samples/api-v1-root-response.json create mode 100644 api-ref/source/watcher-api-versions.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 0598c780f..66e43b637 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -6,6 +6,7 @@ Watcher API .. rest_expand_all:: +.. include:: watcher-api-versions.inc .. include:: watcher-api-v1-audittemplates.inc .. include:: watcher-api-v1-audits.inc .. include:: watcher-api-v1-actionplans.inc @@ -13,4 +14,4 @@ Watcher API .. include:: watcher-api-v1-goals.inc .. include:: watcher-api-v1-strategies.inc .. include:: watcher-api-v1-services.inc -.. include:: watcher-api-v1-scoring_engines.inc \ No newline at end of file +.. include:: watcher-api-v1-scoring_engines.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index d835cc748..5980c68b2 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -1,3 +1,42 @@ +# variables in header +header_version: + description: | + Specific API microversion used to generate this response. + in: header + required: true + type: string +openstack-api-max-version: + description: | + Maximum API microversion supported by this endpoint, eg. "1.1" + in: header + required: true + type: string +openstack-api-min-version: + description: | + Minimum API microversion supported by this endpoint, eg. "1.0" + in: header + required: true + type: string +openstack-api-version: + description: > + A request SHOULD include this header to indicate to the Watcher API service what + version the client supports. The server will transform the response object into + compliance with the requested version, if it is supported, or return a + 406 Not Acceptable error. + If this header is not supplied, the server will response with server minimum + supported version. + in: header + required: true + type: string +openstack-request-id: + description: > + An unique ID for tracking the request. The request ID associated with the request + appears in the log lines for that request. By default, the middleware configuration + ensures that the request ID appears in the log files. + in: header + required: false + type: string + # Path action_ident: description: | @@ -457,3 +496,29 @@ uuid: in: body required: true type: string + +# Version +version: + description: | + Versioning of this API response, eg. "1.1". + in: body + required: true + type: string +version_description: + description: | + Descriptive text about the Watcher service. + in: body + required: true + type: string +version_id: + description: | + Major API version, eg, "v1" + in: body + required: true + type: string +versions: + description: | + Array of information about currently supported versions. + in: body + required: true + type: array diff --git a/api-ref/source/samples/api-root-response.json b/api-ref/source/samples/api-root-response.json new file mode 100644 index 000000000..5d95e2555 --- /dev/null +++ b/api-ref/source/samples/api-root-response.json @@ -0,0 +1,30 @@ +{ + "default_version": { + "id": "v1", + "links": [ + { + "href": "http://controller:9322/v1/", + "rel": "self" + } + ], + "min_version": "1.0", + "status": "CURRENT", + "max_version": "1.1" + }, + "description": "Watcher is an OpenStack project which aims to improve physical resources usage through better VM placement.", + "name": "OpenStack Watcher API", + "versions": [ + { + "id": "v1", + "links": [ + { + "href": "http://controller:9322/v1/", + "rel": "self" + } + ], + "min_version": "1.0", + "status": "CURRENT", + "max_version": "1.1" + } + ] +} diff --git a/api-ref/source/samples/api-v1-root-response.json b/api-ref/source/samples/api-v1-root-response.json new file mode 100644 index 000000000..92460abda --- /dev/null +++ b/api-ref/source/samples/api-v1-root-response.json @@ -0,0 +1,80 @@ +{ + "scoring_engines": [ + { + "href": "http://controller:9322/v1/scoring_engines/", + "rel": "self" + }, + { + "href": "http://controller:9322/scoring_engines/", + "rel": "bookmark" + } + ], + "media_types": [ + { + "base": "application/json", + "type": "application/vnd.openstack.watcher.v1+json" + } + ], + "links": [ + { + "href": "http://controller:9322/v1/", + "rel": "self" + }, + { + "href": "http://docs.openstack.org/developer/watcher/dev/api-spec-v1.html", + "type": "text/html", + "rel": "describedby" + } + ], + "actions": [ + { + "href": "http://controller:9322/v1/actions/", + "rel": "self" + }, + { + "href": "http://controller:9322/actions/", + "rel": "bookmark" + } + ], + "audit_templates": [ + { + "href": "http://controller:9322/v1/audit_templates/", + "rel": "self" + }, + { + "href": "http://controller:9322/audit_templates/", + "rel": "bookmark" + } + ], + "action_plans": [ + { + "href": "http://controller:9322/v1/action_plans/", + "rel": "self" + }, + { + "href": "http://controller:9322/action_plans/", + "rel": "bookmark" + } + ], + "services": [ + { + "href": "http://controller:9322/v1/services/", + "rel": "self" + }, + { + "href": "http://controller:9322/services/", + "rel": "bookmark" + } + ], + "audits": [ + { + "href": "http://controller:9322/v1/audits/", + "rel": "self" + }, + { + "href": "http://controller:9322/audits/", + "rel": "bookmark" + } + ], + "id": "v1" +} diff --git a/api-ref/source/watcher-api-versions.inc b/api-ref/source/watcher-api-versions.inc new file mode 100644 index 000000000..9b12c9b58 --- /dev/null +++ b/api-ref/source/watcher-api-versions.inc @@ -0,0 +1,81 @@ +.. -*- rst -*- + +============ +API versions +============ + +In order to bring new features to users over time, the Watcher API +supports versioning. There are two kinds of versions in Watcher. + +- ''major versions'', which have dedicated URLs. +- ''microversions'', which can be requested using the + ``OpenStack-API-Version`` header. + +.. note:: The maximum microversion depends on release. + Please reference: + `API Microversion History + `__ + for API microversion history details. + +The Version API resource works differently from other API resources as they *do not* +require authentication. + +If Watcher receives a request with unsupported version, it responds with a 406 Not Acceptable, +along with the -Min- and -Max- headers that it can support. + +List API versions +================= + +.. rest_method:: GET / + +This fetches all the information about all known major API versions in the +deployment. Links to more specific information will be provided for each major +API version, as well as information about supported min and max microversions. + +Normal response codes: 200 + +Request +------- + +Response Example +---------------- + +.. rest_parameters:: parameters.yaml + + - description: version_description + - versions: versions + - version: version + - id: version_id + - links: links + - min_version: openstack-api-min-version + - max_version: openstack-api-max-version + +.. literalinclude:: samples/api-root-response.json + :language: javascript + + +Show v1 API +=========== + +.. rest_method:: GET /v1/ + +Show all the resources within the Watcher v1 API. + +Normal response codes: 200 + +Request +------- + +Response Example +---------------- + +.. rest_parameters:: parameters.yaml + + - id: version_id + - links: links + - OpenStack-API-Version: header_version + - OpenStack-API-Minimum-Version: openstack-api-min-version + - OpenStack-API-Maximum-Version: openstack-api-max-version + +.. literalinclude:: samples/api-v1-root-response.json + :language: javascript