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