From e944685861b1600493a08f83d9d8f32878fd5fe8 Mon Sep 17 00:00:00 2001 From: Hieu LE Date: Fri, 19 Aug 2016 11:12:31 +0700 Subject: [PATCH] Create version api reference Add details for version API of Magnum. Change-Id: Idf4e1ff08963a72dc6eaaee0b64f7a91e6be4891 Implements: blueprint magnum-doc-rest-api --- api-ref/source/parameters.yaml | 67 +++++++++++ .../source/samples/versions-01-get-resp.json | 60 ++++++++++ api-ref/source/samples/versions-get-resp.json | 18 +++ api-ref/source/versions.inc | 104 ++++++++++++++++++ 4 files changed, 249 insertions(+) create mode 100644 api-ref/source/parameters.yaml create mode 100644 api-ref/source/samples/versions-01-get-resp.json create mode 100644 api-ref/source/samples/versions-get-resp.json diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 0000000000..371a358ab8 --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -0,0 +1,67 @@ +description: + description: | + Descriptive text about the Magnum service. + in: body + required: true + type: string +links: + description: | + Links to the resources in question. See `API Guide / Links and + References + `_ + for more info. + in: body + required: true + type: array +name: + description: | + Name of the Container Infrastructure Management API. + in: body + required: true + type: string +request_id: + type: UUID + in: header + required: true + description: | + A unique ID for tracking service request. The request ID associated + with the request by default appears in the service logs. +version: + description: | + The version. + in: body + required: true + type: string +version_id: + type: string + in: body + required: true + description: > + A common name for the version in question. Informative only, it + has no real semantic meaning. +version_max: + type: string + in: body + required: true + description: > + If this version of the API supports microversions, the maximum + microversion that is supported. This will be the empty string if + microversions are not supported. +version_min: + type: string + in: body + required: true + description: > + If this version of the API supports microversions, the minimum + microversion that is supported. This will be the empty string if + microversions are not supported. +version_status: + type: string + in: body + required: true + 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 \ No newline at end of file diff --git a/api-ref/source/samples/versions-01-get-resp.json b/api-ref/source/samples/versions-01-get-resp.json new file mode 100644 index 0000000000..5f02ffdb95 --- /dev/null +++ b/api-ref/source/samples/versions-01-get-resp.json @@ -0,0 +1,60 @@ +{ + "media_types":[ + { + "base":"application/json", + "type":"application/vnd.openstack.magnum.v1+json" + } + ], + "links":[ + { + "href":"http://10.164.180.104:9511/v1/", + "rel":"self" + }, + { + "href":"http://docs.openstack.org/developer/magnum/dev/api-spec-v1.html", + "type":"text/html", + "rel":"describedby" + } + ], + "mservices":[ + { + "href":"http://10.164.180.104:9511/v1/mservices/", + "rel":"self" + }, + { + "href":"http://10.164.180.104:9511/mservices/", + "rel":"bookmark" + } + ], + "bays":[ + { + "href":"http://10.164.180.104:9511/v1/bays/", + "rel":"self" + }, + { + "href":"http://10.164.180.104:9511/bays/", + "rel":"bookmark" + } + ], + "certificates":[ + { + "href":"http://10.164.180.104:9511/v1/certificates/", + "rel":"self" + }, + { + "href":"http://10.164.180.104:9511/certificates/", + "rel":"bookmark" + } + ], + "baymodels":[ + { + "href":"http://10.164.180.104:9511/v1/baymodels/", + "rel":"self" + }, + { + "href":"http://10.164.180.104:9511/baymodels/", + "rel":"bookmark" + } + ], + "id":"v1" +} \ No newline at end of file diff --git a/api-ref/source/samples/versions-get-resp.json b/api-ref/source/samples/versions-get-resp.json new file mode 100644 index 0000000000..c6a50c7f3e --- /dev/null +++ b/api-ref/source/samples/versions-get-resp.json @@ -0,0 +1,18 @@ +{ + "versions":[ + { + "status":"CURRENT", + "min_version":"1.1", + "max_version":"1.3", + "id":"v1", + "links":[ + { + "href":"http://10.164.180.104:9511/v1/", + "rel":"self" + } + ] + } + ], + "name":"OpenStack Magnum API", + "description":"Magnum is an OpenStack project which aims to provide container management." +} \ No newline at end of file diff --git a/api-ref/source/versions.inc b/api-ref/source/versions.inc index e69de29bb2..37ba409f8f 100644 --- a/api-ref/source/versions.inc +++ b/api-ref/source/versions.inc @@ -0,0 +1,104 @@ +.. -*- rst -*- + +============== + API Versions +============== + +In order to bring new features to users over time, the Magnum API +supports versioning. There are two kinds of versions in Magnum. + +- ''major versions'', which have dedicated urls +- ''microversions'', which can be requested through the use of the + ``OpenStack-API-Version``. + +Begining with the Newton release, all API requests support the +``OpenStack-API-Version`` header. This header SHOULD be supplied +with every request; in the absence of this header, each request is treated +as though coming from an older pre-Newton client. This was done to preserve +backwards compatibility as we introduced new features. + +The Version APIs work differently from other APIs as they *do not* +require authentication. + +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 API version, as well as information about supported min and +max microversions. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 503 + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - X-Openstack-Request-Id: request_id + - versions: version + - status: version_status + - min_version: version_min + - max_version: version_max + - id: version_id + - links: links + - name: name + - description: description + +Response Example +---------------- + +.. literalinclude:: samples/versions-get-resp.json + :language: javascript + + +Show v1 API Version +==================================== + +.. rest_method:: GET /v1/ + +Show all the resources within the Magnum v1 API. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 503 + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - X-Openstack-Request-Id: request_id + - id: version_id + - links: links + +.. note:: + + The ``media-types`` parameters in the response are + vestigial and provide no useful information. They will probably be + deprecated and removed in the future. + + +Response Example +---------------- + +.. literalinclude:: samples/versions-01-get-resp.json + :language: javascript \ No newline at end of file