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@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > -- Sean Dague Samsung Research America s...@dague.net / sean.da...@samsung.com http://dague.net
signature.asc
Description: OpenPGP digital signature
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
