Bug 894895

Writing public documentation for _clients_ of openstack installations is currently problematic.

- Being a fast moving project, features and APIs are being added frequently.
- Not all installations will be based on the same release or version

The question for end users therefor is "how can I tell if the installation I'm connected to supports feature X (or has bugfix Y)?"

Adding such an API would allow documentation/howto writers to clearly articulate the necessary requirements and for readers to know if things are not working because they do not meet them (as compared to just doing it wrong).

Example: I was told that for a particular networking feature I needed quantum instead of nova.  It should be possible to answer whether I meet this criteria without being (or having access to) the person who installed openstack.

The right way to approach this is not detecting the version of the service that's running, it's detecting features or capabilities.  There is some support for this already, but it needs to be improved, and needs to be made more consistent among each of the APIs.  This is currently being actively discussed upstream.  See these references:

http://lists.openstack.org/pipermail/openstack-dev/2013-May/008436.html

https://etherpad.openstack.org/api-version-discovery-proposal

(In reply to Andrew Beekhof from comment #1)
> Example: I was told that for a particular networking feature I needed
> quantum instead of nova.  It should be possible to answer whether I meet
> this criteria without being (or having access to) the person who installed
> openstack.

This one is pretty easy.  Quantum is its own service that exposes its own API.  Either that API is present or not.

I realize that's not an answer to the more general problem, but just pointing out a solution for that particular example.  :-)

Some additional notes on what already exists, at least in the compute (nova) API:


GET /

{"versions": [{"status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "id": "v2.0", "links": [{"href": "http://162.209.6.241:8774/v2/", "rel": "self"}]}]}


GET /v2/

version": {"status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "media-types": [{"base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2"}, {"base": "application/json", "type": "application/vnd.openstack.compute+json;version=2"}], "id": "v2.0", "links": [{"href": "http://162.209.6.241:8774/v2/", "rel": "self"}, {"href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", "rel": "describedby"}, {"href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby"}]}}


GET /v2/<tenant-id>/extensions/

{"extensions": [{"updated": "2011-06-09T00:00:00+00:00", "name": "Multinic", "links": [], "namespace": "http://docs.openstack.org/compute/ext/multinic/api/v1.1", "alias": "NMN", "description": "Multiple network support."},
...
<snipped really long list of extensions>


In development of Havana, a new rev of the API is being added (v3), where we will be further improving on this.  The details may depend on where the cross-project discussion lands.  Some related blueprints where you can track patches going up in this area:

https://blueprints.launchpad.net/nova/+spec/v3-api-extension-framework
https://blueprints.launchpad.net/nova/+spec/v3-api-extension-versioning