Open Stack

On Thu, 2014-02-13 at 08:37 -0500, Sean Dague wrote:
> 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.

So firstly i absolutely agree that version discovery is an API change.
More that that it is the only API that we cannot version so we are stuck
with whatever we choose indefinitely. 

The reason i suggested 'stable' is because keystone is the point of
contact here. Theoretically ever other service could add a new route
(eg /info) which defined whatever scheme we choose, and have the service
catalog point to that and there should be no difference in the
experience. Keystone is different in that it is always called and
probably the only client even attempting to do discovery at the moment.

Having said that we have the opportunity thanks to point 3 to add new
endpoints without the 'values' key that can follow the other examples. 

What i would then like to know is what are the definitions and priority
of the 'CURRENT' scheme? 'EXPERIMENTAL' is somewhat obvious but what is
the difference between 'CURRENT' and 'SUPPORTED'? We need to define a
strict definition of what is allowed here, what values are considered
stable vs unstable, and what is the priority ordering. 

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

Strictly speaking probably. I thought the 300 made some sense as
requests to this page are sort of like a directory where you choose
where to go next, even if there is only one choice. Probably we should
just return 200 all the time as it was a successful operation and we
aren't redirecting automatically. 

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

Yes, this is something that will need to be supported for a long time
anyway. This guide is as much as anything a reference for new projects
for what the best behaviour is so whilst we may not be able to address
it for existing projects new projects should try to follow best
practice. 

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