Add version api ref
Change-Id: I93cb484a1f3ae533558ecde0cd79c8b6b2fb18f1
This commit is contained in:
parent
a30ee72ec5
commit
f7dcefb554
@ -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
|
||||
|
@ -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
|
||||
|
30
api-ref/source/samples/api-root-response.json
Normal file
30
api-ref/source/samples/api-root-response.json
Normal 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"
|
||||
}
|
||||
]
|
||||
}
|
80
api-ref/source/samples/api-v1-root-response.json
Normal file
80
api-ref/source/samples/api-v1-root-response.json
Normal 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"
|
||||
}
|
81
api-ref/source/watcher-api-versions.inc
Normal file
81
api-ref/source/watcher-api-versions.inc
Normal 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
|
Loading…
Reference in New Issue
Block a user