Difference between revisions of "VersionDiscovery"

Revision as of 06:48, 17 February 2014

Summary

Each service should advertise the API versions exposed by the service and the endpoint from where that service can be accessed. The purpose of this document is to standardize the format for these responses.

Individual Version Entry

An API version is exposed as a series of attributes:

   {
       "id": "--id--",
       "status": "--status--",
       "links": [
           {
               "href": "--url--",
               "rel": "--rel--"
           }
       ],
       "media-types": [
           {
               "base": "--base--",
               "type": "--type--"
           }
       ]
   }

Individual version base URLs (eg at "http://localhost:5000/v3") will return a version object under the key of "version" with a status of 200 OK. Discovery endpoints should not be access controlled.

eg

   Status: 200 OK
   {
       "version": {
           "id": "v3.0",
           "status": "stable",
           "updated": "2013-03-06T00:00:00Z",
           "media-types": [
               {
                   "base": "application/json",
                   "type": "application/vnd.openstack.identity-v3+json"
               },
               {
                   "base": "application/xml",
                   "type": "application/vnd.openstack.identity-v3+xml"
               }
           ],
           "links": [
               {
                   "href": "http://localhost:5000/v3/",
                   "rel": "self"
               }
           ]
       }
   }

By convention an endpoint version will be mounted under the subpath /v{major} eg /v3 as shown above, however this is not required so long as the URLs available from discovery are correct.

id

This is a required field

The id is the version identifier of an API endpoint. id is specified as a string in the format "v{major}.{minor}" for example "v2.1". Backwards compatibility is implied by version numbering and an interface with a higher minor version number is expected to incorporate all preceding versions. For example an advertised version of "v2.3" will respond as specified to versions "v2.0", "v2.1", and "v2.2".

status

This is a required field

The status reflects the state of the endpoint on the service. The following table presents endpoints in the order in which they should be prioritized. Stable defines whether the API is undergoing changes, eg if the API version is still under development.

links

This is a required field and a rel of self link must be present. Each link object must contain at least a rel and href element.

links is specified as a list of objects containing:

• rel - The type of link being referenced. Supported `rel` types are:

• self - The base URL for this version.
• describedby - Documentation of this version of the api.

• type - The mime type that is available at the specified link. This is generally used only in conjunction with the describedby link type and describes the type of documentation. eg "application/pdf"

• href - A link to the base endpoint of the API. This is specified in normal href syntax, in that it supports:

• absolute URLs, eg 'http://service/'
• relative URLs, eg '/compute' or 'compute' . This extends to allowing path traversal using the '.' and '..' paths.

Relative links should be preferred here unless the service exists on a different host or protocol. This means that the typical self link when requesting a versioned endpoint (eg '/v3' ) is going to simply be '.'.

A difference to the standard href linking syntax is that all urls provided by the href element are read to be folder elements. Eg If a request to 'http://service/prefix' returned an endpoint of 'v1' then the endpoint is deemed to be at 'http://service/prefix/v1/' as if the request was sent to 'http://service/prefix/' and the endpoint returned was 'v1/' (note the trailing slashes). This is intended to allow some leeway in configuration for operators and maintain backwards compatability and not an indication that trailing slashes should be removed from the link.

updated

An ISO8601 formatted timestamp indicating the last update of this version status or number. This is updated when a new version is available or the status of the endpoint changes. It does not require changing on every API update to an unstable endpoint.

media-types

The formats in which this API is exposed. It is provided in a list of objects consisting of:

• base - The basic mime type of the endpoint, eg `application/json`
• type - A detailed specific application mime type, eg "application/vnd.openstack.volume+json;version=1"

Root Discovery

The base entry point to a service will expose a list of versions keyed under the `versions` key. The information in each version information should be exactly the same as what is provided by each versioned endpoint. The return status code should be 300 Multiple Choices (even if there is only 1 version available).

Discovery endpoints should not be access controlled.

Because greater minor versions include all smaller minor versions individually minor versions should not be included but considered available by other services.

eg.

   Status: 300
   {
       "versions": [
           {
               "status": "stable",
               "updated": "2013-03-06T00:00:00Z",
               "media-types": [
                   {
                       "base": "application/json",
                       "type": "application/vnd.openstack.identity-v3+json"
                   },
                   {
                       "base": "application/xml",
                       "type": "application/vnd.openstack.identity-v3+xml"
                   }
               ],
               "id": "v3.0",
               "links": [
                   {
                       "href": "/v3/",
                       "rel": "self"
                   }
               ]
           },
           {
               "status": "stable",
               "updated": "2013-03-06T00:00:00Z",
               "media-types": [
                   {
                       "base": "application/json",
                       "type": "application/vnd.openstack.identity-v2.0+json"
                   },
                   {
                       "base": "application/xml",
                       "type": "application/vnd.openstack.identity-v2.0+xml"
                   }
               ],
               "id": "v2.0",
               "links": [
                   {
                       "href": "/v2.0/",
                       "rel": "self"
                   },
                   {
                       "href": "http://docs.openstack.org/api/openstack-identity-service/2.0/content/",
                       "type": "text/html",
                       "rel": "describedby"
                   },
                   {
                       "href": "http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf",
                       "type": "application/pdf",
                       "rel": "describedby"
                   }
               ]
           }
       ]
   }