Add version api ref

Change-Id: I93cb484a1f3ae533558ecde0cd79c8b6b2fb18f1
This commit is contained in:
licanwei 2018-12-04 18:31:20 +08:00
parent a30ee72ec5
commit f7dcefb554
5 changed files with 258 additions and 1 deletions

View File

@ -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
.. include:: watcher-api-v1-scoring_engines.inc

View File

@ -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

View File

@ -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"
}
]
}

View File

@ -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"
}

View File

@ -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
<https://docs.openstack.org/watcher/latest/contributor/api_microversion_history.html>`__
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