Open Stack

Hi all,

I am one of i think a number of efforts trying to make clients be interoperable between different versions of an API.

What i would like to talk about specifically here are the inconsistencies in the version listing of the different servers when you query the root GET '/' and GET '/vX' address for versions. This is a badly formatted sampling of the policies out there: http://paste.openstack.org/show/64770/

This is my draft of a common solution https://wiki.openstack.org/wiki/VersionDiscovery which has some changes for everyone, but I at least hope can be a guide for new services and a target for the existing

There are a number of major inconsistencies that i hope to address:

1. The 'status' of an API. 

Keystone uses the word 'stable' to indicate a stable API, there are a number of services using 'CURRENT' and i'm not sure what 'SUPPORTED' is supposed to mean here. In general I think 'stable' makes the most sense and in many ways keystone has to be the leader here as it is the first contact. Any ideas how to convert existing APIs to this scheme? 

2. HTTP Status

Some services are 200, some 300. It also doesn't matter how many responses there are in this status. 

3. Keystone uses ['versions']['values']

Yep. Not sure why that is. Sorry, we should be able to have a copy under 'values' and one in the root 'versions' simultaneously for a while and then drop the 'values' in some future release. 

4. Glance does a version entry for each minor version. 

Seperate entries for v2.2, v2.1, v2.0. They all point to the same place so IMO this is unnecessary. 

5. Differences between entry in GET '/' and GET '/vX'

There is often a log more information in GET '/vX' like media-type that is not present in the root. I'm not sure if this was on purpose but i think it easier (and less lookups) to have this information consistent.

6. GET '/' is unrestricted. GET '/vX' is often token restricted. 

Keystone allows access to /v2.0 and /v3 but most services give a HTTP Unauthorized. This is a real problem for discovery because we need to be able to evaluate the endpoints in the service catalog. I think we need to make these unauthorized.

Please have a look over the wiki page and how it addresses the above and fits into the existing schemes and reply with any comments or problems that you see. Is this going to mess with any pre-existing clients?

Then is there somewhere we can do 'new project guidelines' that we can link this from?


Jamie


PS. This is the script I used for the sampling if you want to test yourself: http://paste.openstack.org/show/65015/ it makes assumptions on URL structures and it won't pass code review.