Jump to: navigation, search

VersionDiscovery

Revision as of 11:40, 12 February 2014 by Jamielennox (talk | contribs) (Created page with "== 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 ...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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 pages.

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

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

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

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
  • 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 - Used only in conjunction with the describedby link type. The format of the documentation available at the href.

updated

An ISO8601 formatted timestamp of the last time that the API version number was updated.

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": "http://localhost:5000/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": "http://localhost:5000/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"
                   }
               ]
           }
       ]
   }