Open Stack

On 02/13/2014 07:50 AM, Jamie Lennox wrote:
> 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? 

From that link, only Keystone is different. Glance, Cinder, Neutron,
Nova all use CURRENT. So while not ideal, I'm not sure why we'd change
the rest of the world to match keystone, vs. changing keystone to match
the rest of the world.

Also realize changing version discovery itself is an API change, so my
feeling is this should be done in the smallest number of places possible.

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

Ideally - 300 should be returned if there are multiple versions, and 200
otherwise.

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

Again, keystone seems to be the odd man out here.

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

Probably agreed, curious if any Glance folks know of w reason for it.

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

Agreed, I expect it's historical following of nova that media-type is
not in the root. I think it's fixable.

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

Agreed, however due to the way the wsgi stacks work in these projects,
this might not be trivial. I'd set that as a goal to address.

> 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.
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> 


-- 
Sean Dague
Samsung Research America
sean at dague.net / sean.dague at samsung.com
http://dague.net

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 482 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140213/cc723251/attachment.pgp>