On Mon, 2014-02-17 at 16:09 +1000, Jamie Lennox wrote: > 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@lists.openstack.org > > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > > > > > > _______________________________________________ > > OpenStack-dev mailing list > > OpenStack-dev@lists.openstack.org > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > > _______________________________________________ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Document updated to reflect all above points and those made by Dean. I haven't added anything about revisions as that will be new to all services and i'm just looking to define the best and most common from what currently exists in a compatible way. Please review. Also is there somewhere i can link this to to make sure it is seen by people creating a new project? Jamie _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
