API Working Group/Current Design/Version Responses

= Analysis =

What responses are being returned for version requests?

This analysis is specifically asking for versions reported by an API server through a GET request at "/", "/version", "/v1", or similar.

The Version Discovery page on the OpenStack wiki is being used as a reference point in this analysis.

= Current Design =

Cinder
Cinder API reference

Examples
GET / {   "versions": [ {           "id": "v1.0", "links": [ {                   "href": "http://docs.openstack.org/", "rel": "describedby", "type": "text/html" },               {                    "href": "http://192.168.122.88:8776/v1/", "rel": "self" }           ],            "media-types": [ {                   "base": "application/json", "type": "application/vnd.openstack.volume+json;version=1" }           ],            "min_version": "", "status": "DEPRECATED", "updated": "2016-05-02T20:25:19Z", "version": "" },       {            "id": "v2.0", "links": [ {                   "href": "http://docs.openstack.org/", "rel": "describedby", "type": "text/html" },               {                    "href": "http://192.168.122.88:8776/v2/", "rel": "self" }           ],            "media-types": [ {                   "base": "application/json", "type": "application/vnd.openstack.volume+json;version=1" }           ],            "min_version": "", "status": "SUPPORTED", "updated": "2014-06-28T12:20:21Z", "version": "" },       {            "id": "v3.0", "links": [ {                   "href": "http://docs.openstack.org/", "rel": "describedby", "type": "text/html" },               {                    "href": "http://192.168.122.88:8776/v3/", "rel": "self" }           ],            "media-types": [ {                   "base": "application/json", "type": "application/vnd.openstack.volume+json;version=1" }           ],            "min_version": "3.0", "status": "CURRENT", "updated": "2016-02-08T12:20:21Z", "version": "3.15" }   ] }

GET /v2

{   "version": { "id": "v2.0", "links": [ {               "href": "http://23.253.211.234:8776/v2/v2.0", "rel": "self" }       ],        "media-types": [ {               "base": "application/xml", "type": "application/vnd.openstack.volume+xml;version=1" },           {                "base": "application/json", "type": "application/vnd.openstack.volume+json;version=1" }       ],        "status": "CURRENT" } }

Glance
Image service API v1 reference

Image service API v2 reference

Only GET / and GET /versions are documented as providing a versions response.

Examples
Same response for GET / and GET /versions

{   "versions": [ {           "id": "v2.3", "links": [ {                   "href": "http://brianr-dev10:9292/v2/", "rel": "self" }           ],            "status": "CURRENT" },       {            "id": "v2.2", "links": [ {                   "href": "http://brianr-dev10:9292/v2/", "rel": "self" }           ],            "status": "SUPPORTED" },       {            "id": "v2.1", "links": [ {                   "href": "http://brianr-dev10:9292/v2/", "rel": "self" }           ],            "status": "SUPPORTED" },       {            "id": "v2.0", "links": [ {                   "href": "http://brianr-dev10:9292/v2/", "rel": "self" }           ],            "status": "SUPPORTED" },       {            "id": "v1.1", "links": [ {                   "href": "http://brianr-dev10:9292/v1/", "rel": "self" }           ],            "status": "SUPPORTED" },       {            "id": "v1.0", "links": [ {                   "href": "http://brianr-dev10:9292/v1/", "rel": "self" }           ],            "status": "SUPPORTED" }   ] }

GET /v2 returns 302 Found.

GET /v2/ returns 404 Not Found.

Keystone
Keystone v2 API reference

Keystone v3 API reference

Examples
GET /

{   "versions": { "values": [ {               "id": "v3.4", "links": [ {                       "href": "http://10.0.1.107:5000/v3/", "rel": "self" }               ],                 "media-types": [ {                       "base": "application/json", "type": "application/vnd.openstack.identity-v3+json" }               ],                 "status": "stable", "updated": "2015-03-30T00:00:00Z" },            {                "id": "v2.0", "links": [ {                       "href": "http://10.0.1.107:5000/v2.0/", "rel": "self" },                    {                        "href": "http://docs.openstack.org/", "rel": "describedby", "type": "text/html" }               ],                 "media-types": [ {                       "base": "application/json", "type": "application/vnd.openstack.identity-v2.0+json" }               ],                 "status": "stable", "updated": "2014-04-17T00:00:00Z" }       ]    } }

GET /v2.0/

{   "version": { "id": "v2.0", "links": [ {               "href": "http://10.0.1.107:5000/v2.0/", "rel": "self" },            {                "href": "http://docs.openstack.org/", "rel": "describedby", "type": "text/html" }       ],         "media-types": [ {               "base": "application/json", "type": "application/vnd.openstack.identity-v2.0+json" }       ],         "status": "stable", "updated": "2014-04-17T00:00:00Z" } }

GET /v3/

{   "version": { "id": "v3.4", "links": [ {               "href": "http://10.0.1.107:5000/v3/", "rel": "self" }       ],         "media-types": [ {               "base": "application/json", "type": "application/vnd.openstack.identity-v3+json" }       ],         "status": "stable", "updated": "2015-03-30T00:00:00Z" } }

Manila
Shared File Systems service API v1 (Supported) reference

Shared File Systems service API v2 (Current) reference

Examples
GET /

{    "versions":[ {          "status":"SUPPORTED", "updated":"2015-08-27T11:33:21Z", "links":[ {                "href":"http://docs.openstack.org/", "type":"text/html", "rel":"describedby" },           {                 "href":"http://192.168.10.11:8786/v1/", "rel":"self" }        ],         "min_version":"", "version":"", "media-types":[ {                "base":"application/json", "type":"application/vnd.openstack.share+json;version=1" }        ],         "id":"v1.0" },     {           "status":"CURRENT", "updated":"2015-08-27T11:33:21Z", "links":[ {                "href":"http://docs.openstack.org/", "type":"text/html", "rel":"describedby" },           {                 "href":"http://192.168.10.11:8786/v2/", "rel":"self" }        ],         "min_version":"2.0", "version":"2.8", "media-types":[ {                "base":"application/json", "type":"application/vnd.openstack.share+json;version=1" }        ],         "id":"v2.0" }  ] }

GET /v1/

{    "versions":[ {          "status":"SUPPORTED", "updated":"2015-08-27T11:33:21Z", "links":[ {                "href":"http://docs.openstack.org/", "type":"text/html", "rel":"describedby" },           {                 "href":"http://192.168.10.11:8786/v1/", "rel":"self" }        ],         "min_version":"", "version":"", "media-types":[ {                "base":"application/json", "type":"application/vnd.openstack.share+json;version=1" }        ],         "id":"v1.0" }  ] }

GET /v2/

{    "versions":[ {          "status":"CURRENT", "updated":"2015-08-27T11:33:21Z", "links":[ {                "href":"http://docs.openstack.org/", "type":"text/html", "rel":"describedby" },           {                 "href":"http://192.168.10.11:8786/v2/", "rel":"self" }        ],         "min_version":"2.0", "version":"2.8", "media-types":[ {                "base":"application/json", "type":"application/vnd.openstack.share+json;version=1" }        ],         "id":"v2.0" }  ] }.

Nova
Nova API reference

Examples
GET /

{   "versions": [ {           "id": "v2.0", "links": [ {                   "href": "http://10.0.1.107:8774/v2/", "rel": "self" }           ],            "status": "SUPPORTED", "version": "", "min_version": "", "updated": "2011-01-21T11:33:21Z" },       {            "id": "v2.1", "links": [ {                   "href": "http://10.0.1.107:8774/v2.1/", "rel": "self" }           ],            "status": "CURRENT", "version": "2.12", "min_version": "2.1", "updated": "2013-07-23T11:33:21Z" }   ] }

GET /v2/

{   "version": { "id": "v2.0", "links": [ {               "href": "http://10.0.1.107:8774/v2/", "rel": "self" },            {                "href": "http://docs.openstack.org/", "rel": "describedby", "type": "text/html" }       ],         "media-types": [ {               "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" }       ],         "min_version": "", "status": "SUPPORTED", "updated": "2011-01-21T11:33:21Z", "version": "" } } GET /v2.1/

{   "version": { "id": "v2.1", "links": [ {               "href": "http://10.0.1.107:8774/v2.1/", "rel": "self" },            {                "href": "http://docs.openstack.org/", "rel": "describedby", "type": "text/html" }       ],         "media-types": [ {               "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2.1" }       ],         "min_version": "2.1", "status": "CURRENT", "updated": "2013-07-23T11:33:21Z", "version": "2.12" } }

Sahara
Sahara API reference

Examples
GET /

{   "versions": [ {           "id": "v1.0", "status": "SUPPORTED" },        {            "id": "v1.1", "status": "CURRENT" }   ] }

GET /v1/ returns 404 Not Found.

GET /v1.0/ returns 404 Not Found.

GET /v1.1/ returns 404 Not Found.

Telemetry
Telemetry is divided into Ceilometer, Aodh and Gnocchi these days, each with a separate API.

GET / requires auth, which is probably a bug.

Note: cdent used gabbi to make these discoveries.

Ceilometer
Requires Authentication

GET /

{  "versions" : { "values" : [ {           "updated" : "2013-02-13T00:00:00Z", "status" : "stable", "media-types" : [ {                 "base" : "application/json", "type" : "application/vnd.openstack.telemetry-v2+json" },              {                  "type" : "application/vnd.openstack.telemetry-v2+xml", "base" : "application/xml" }           ],            "id" : "v2", "links" : [ {                 "href" : "http://localhost:8777/v2", "rel" : "self" },              {                  "href" : "http://docs.openstack.org/", "type" : "text/html", "rel" : "describedby" }           ]         }      ]   } }

GET /v2 is a 404

Aodh
Requires authentication

GET /

{  "versions" : { "values" : [ {           "updated" : "2013-02-13T00:00:00Z", "media-types" : [ {                 "type" : "application/vnd.openstack.telemetry-v2+json", "base" : "application/json" },              {                  "base" : "application/xml", "type" : "application/vnd.openstack.telemetry-v2+xml" }           ],            "links" : [ {                 "rel" : "self", "href" : "http://localhost:8042/v2" },              {                  "type" : "text/html", "rel" : "describedby", "href" : "http://docs.openstack.org/" }           ],            "id" : "v2", "status" : "stable" }     ]   } }

GET /v2 is a 404

Gnocchi
Requires authentication in default devstack

GET /

{  "versions" : [ {        "links" : [ {              "rel" : "self", "href" : "http://localhost:8041/v1/" }        ],         "updated" : "2015-03-19", "status" : "CURRENT", "id" : "v1.0" }  ] }

GET /v1/

{  "links" : [ {        "href" : "http://localhost:8041/v1", "rel" : "self" },     {         "href" : "http://localhost:8041/v1/aggregation", "rel" : "aggregation" },     {         "href" : "http://localhost:8041/v1/archive_policy", "rel" : "archive_policy" },     {         "rel" : "archive_policy_rule", "href" : "http://localhost:8041/v1/archive_policy_rule" },     {         "href" : "http://localhost:8041/v1/capabilities", "rel" : "capabilities" },     {         "href" : "http://localhost:8041/v1/metric", "rel" : "metric" },     {         "href" : "http://localhost:8041/v1/resource", "rel" : "resource" },     {         "href" : "http://localhost:8041/v1/search", "rel" : "search" },     {         "rel" : "status", "href" : "http://localhost:8041/v1/status" }  ],   "version" : "1.0" }