Jump to: navigation, search

VersionDiscovery

Revision as of 06:10, 17 February 2014 by Jamielennox (talk | contribs) (Root Discovery)

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. Defined status in order of stability:

  • unstable - the API is in development but is not yet completed and supported.
  • stable - the API is supported and maintained by the server.

links

This is a required field and a rel of self link must be present

links is specified as a list of objects containing:

  • 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 service/compute

Relative links should be preferred here unless the service exists on a different host or protocol.

  • 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 documentattion. eg "application/pdf"

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