106 lines
2.1 KiB
ReStructuredText
106 lines
2.1 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
==============
|
|
API Versions
|
|
==============
|
|
|
|
In order to bring new features to users over time, the Masakari API
|
|
supports versioning.
|
|
|
|
- ''major versions'', which have dedicated urls
|
|
|
|
The Version APIs work differently from other APIs as they *do not*
|
|
require authentication.
|
|
|
|
List All Major 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.
|
|
|
|
Response Codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- versions: versions
|
|
- id: version_id
|
|
- status: version_status
|
|
- links: links
|
|
- version: version_max
|
|
- min_version: version_min
|
|
|
|
.. note::
|
|
|
|
The ``updated`` parameter in the response is vestigial and provides
|
|
no useful information.
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
This demonstrates the expected response from a bleeding edge server
|
|
that supports up to the current version.
|
|
|
|
.. literalinclude:: /../../doc/api_samples/versions/versions-get-resp.json
|
|
:language: javascript
|
|
|
|
|
|
Show Details of Specific API Version
|
|
====================================
|
|
|
|
.. rest_method:: GET /{api_version}/
|
|
|
|
This gets the details of a specific API at its root. Nearly all this
|
|
information exists at the API root, so this is mostly a redundant
|
|
operation.
|
|
|
|
Response Codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- api_version: api_version
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- version: version
|
|
- id: version_id
|
|
- status: version_status
|
|
- links: links
|
|
- version: version_max
|
|
- min_version: version_min
|
|
|
|
.. note::
|
|
|
|
The ``updated`` and ``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
|
|
----------------
|
|
|
|
This is an example of a ``GET /v1/`` on a relatively current server.
|
|
|
|
.. literalinclude:: /../../doc/api_samples/versions/v1-version-get-resp.json
|
|
:language: javascript |