Re: [openstack-dev] Version Discovery Standardization
On Thu, 2014-02-13 at 19:35 -0700, Christopher Yeoh wrote: On Thu, 13 Feb 2014 21:10:01 -0500 Sean Dague s...@dague.net wrote: On 02/13/2014 08:28 PM, Christopher Yeoh wrote: On Thu, 13 Feb 2014 15:54:23 -0500 Sean Dague s...@dague.net wrote: So one question I have around a global version is what happens when we have the following situation: - Extension (not core) A is bumped to version 3, global version bumped to 3.01 - Extension B (not core) is bumped to version 6, global version bumped to 3.02 but the deployer for $REASONS (perhaps stability/testing/whatever) really wants to deploy with version 2 of A but version 6 of B. With versioning just on the extensions individually they're ok, but I don't think there's any real sane way to get a global micro version calculated for this scenario that makes sense to the end user. So there remains a question about extensions vs. global version. I think a big piece of this is anything which is a core extension, So to reduce confusion I've been trying to introduce the nomenclature of everything is a plugin. And then some plugins are compulsory (eg core) and others are optional (extensions) stops getting listed as an extension and instead is part of properly core and using the global version. How extensions impact global version is I think an open question. But Nova OS API is actually really weird if you think about it relative to other cloud APIs (ec2, gce, softlayer). We've defined it not as the Nova API, but as a small core compute API, and many dozens optional features, which every deployer makes decisions on what comes and goes. I agree we need to think through a few things. But I think that if we get to v3, only to have to do a ton more stuff for v4, and take 2 more years to get there, we're in a world of hurt. The current model of API revisions as giant big bangs isn't good for any one. A way to make an API be able to grow over time, in a backwards compatible way, and some mechanism to deprecate and remove a feature over time would be much more advantageous to our consumers. I agree we don't want to avoid another big bang version change for as long as we can. Given that we have extensions (and I know that some people really don't like that) however I'd be a lot more comfortable if this minor global version was only bumped when there were changes to the core plugins or a plugin was added to the core (I don't think we can ever remove them from core within a major version). There should be a high bar on making any changes to core plugins (even though they are backwards compatible). I'm also fine with core plugins not appearing in the /v3/extensions list. Its a simple enough change and agree that it will reduce confusion over interoperability between openstack clouds. Chris Caveat: IANAND (I am not a nova dev) and i'm not familiar with nova's plugins so i'm working with a standard definition of a plugin and define for the rest of this email that: - An extension is something that adds paths or features to the API. - A plugin is code that is loaded to do some work. To my mind talking of plugins is confusing the API with the implementation. The sum total of the core plugins is the interface that a project has to implement to be compatible with nova and is defined as the core API. This API is the thing that we are versioning and that should be done globally and semantically. If plugins are allowed to directly define the API and some combination of plugins is loaded that does not provided the API specified by the version then the server is in error advertising that it supports that API version. An extension provides additional methods or data to the API (whether this is loaded via plugin or always available). Being that extensions are not covered by the API definition then they should provide there own version discovery information. This means that an extension can define an interface and that can co-exist with any version of the core API (though i can definitely see the use case for this extension requires at least this version of the API). By definition anything in the core API is not an extension and should not be listed as such. Version discovery could be done for extensions either as a part of GET / but i think it makes sense for that to be part of the project specific API (eg GET /v3/extensions) as that information may need to change in future API versions. Also this is kind of outside the scope of what we are talking about here. For now all we need is a way of determining core API versions and then extension discovery is a subset of that. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list
Re: [openstack-dev] Version Discovery Standardization
On Thu, 2014-02-13 at 08:45 -0600, Dean Troyer wrote:
FWIW, an early proposal to address this, as well as capability
discovery, still lives
at https://etherpad.openstack.org/p/api-version-discovery-proposal.
I've lost track of where this went, and even which design summit this
is from, but I've been using it as a sanity check for the discovery
bits in OSC.
Yes, i've seen that one. It's more client side how we should work with
it though. If we can standardize the server side response then the
client side becomes much more reusable.
On Thu, Feb 13, 2014 at 6:50 AM, Jamie Lennox jamielen...@redhat.com
wrote:
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.
I agree, however from a client discovery process point-of-view, you do
not necessarily have an endpoint until after you auth and get a
service catalog anyway. For example, in the specific case of
OpenStackClient Help command output, the commands listed may depend on
the desired API version. To get the endpoints to query for version
support still requires a service catalog so nothing really changes
there.
Yes, i had thought of that afterward and we can send the token to the
endpoint. From a standards document though it'd be better if we didn't
have to.
And this doesn't even touch on the SC endpoints that include things
like tenant/project id...
Yuk. Yes, a problem with this is that entries in the service catalog
that have a project id in them don't currently present version
information at that endpoint. I'd be interested in fixing this but as
it's going to need to be backwards compatible with the current state
it's not really a priority.
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?
* id: Let's either make this a real semantic version so we can parse
and use the major.minor.patch components (and dump the 'v') or make it
an identifier that matches the URL path component. Right now
Do we need patch on API versions? I was aiming for standards rather than
improvement here but i guess this is the right time to fix something
like this.
* updated: I think it would be a friendly gesture to update this for
unstable changes as the id is likely to not be updated mid-stream.
During debugging I would want to be able to verify exactly which
implementation I was talking to anyway.
So i was thinking the way to do that would be to define two endpoints eg
a stable v3.2 and an unstable v3.3 that reference the same endpoint.
There are two transitional things to also consider:
* We have to produce a discovery mechanism that takes in to account
the historical authentication URLs published by deployments that
include a version. ayoung's Ml thread last week discussed this a bit,
we should document the approaches that we're testing and why they do
or do not work.
Right and we need another talk about this, but let's leave this about
defining a standard that new projects should adhere to and slowly moving
the existing ones.
* There are real-world deployments that do not configure
admin_endpoint and/or public_endpoint in keystone.conf. Discovery is
really useless if the URL you are given is
https://localhost:5000/v2.0. Do we need to talk about another
horrible horrible hack to deal with these or are these deployments
going to be left out in the cold?
Right, this is more infuriating with keystone that uses admin_url which
is not defined as either public or internal. Which URL should be present
on that discover page?
From the server side to counter this i very specifically put a clause in
the wiki page to say that discover links can be relative and i'll change
that now to SHOULD be relative. This way a link is just defined as
/v2.0 and you can use whatever host got you to that point. The only
problem i see here is what is the relative self link from GET /v2.0
should it just be { rel: self, href: }, is href excluded or
None?
The client side is going to be ugly again and we should talk but it's
outside scope for this.
dt
--
Dean Troyer
dtro...@gmail.com
___
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
Re: [openstack-dev] Version Discovery Standardization
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
Re: [openstack-dev] Version Discovery Standardization
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
[openstack-dev] Version Discovery Standardization
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. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Version Discovery Standardization
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
Re: [openstack-dev] Version Discovery Standardization
FWIW, an early proposal to address this, as well as capability discovery, still lives at https://etherpad.openstack.org/p/api-version-discovery-proposal. I've lost track of where this went, and even which design summit this is from, but I've been using it as a sanity check for the discovery bits in OSC. On Thu, Feb 13, 2014 at 6:50 AM, Jamie Lennox jamielen...@redhat.comwrote: 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. I agree, however from a client discovery process point-of-view, you do not necessarily have an endpoint until after you auth and get a service catalog anyway. For example, in the specific case of OpenStackClient Help command output, the commands listed may depend on the desired API version. To get the endpoints to query for version support still requires a service catalog so nothing really changes there. And this doesn't even touch on the SC endpoints that include things like tenant/project id... 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? * id: Let's either make this a real semantic version so we can parse and use the major.minor.patch components (and dump the 'v') or make it an identifier that matches the URL path component. Right now * updated: I think it would be a friendly gesture to update this for unstable changes as the id is likely to not be updated mid-stream. During debugging I would want to be able to verify exactly which implementation I was talking to anyway. There are two transitional things to also consider: * We have to produce a discovery mechanism that takes in to account the historical authentication URLs published by deployments that include a version. ayoung's Ml thread last week discussed this a bit, we should document the approaches that we're testing and why they do or do not work. * There are real-world deployments that do not configure admin_endpoint and/or public_endpoint in keystone.conf. Discovery is really useless if the URL you are given is https://localhost:5000/v2.0. Do we need to talk about another horrible horrible hack to deal with these or are these deployments going to be left out in the cold? dt -- Dean Troyer dtro...@gmail.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Version Discovery Standardization
On 02/13/2014 09:45 AM, Dean Troyer wrote:
FWIW, an early proposal to address this, as well as capability
discovery, still lives
at https://etherpad.openstack.org/p/api-version-discovery-proposal.
I've lost track of where this went, and even which design summit this
is from, but I've been using it as a sanity check for the discovery bits
in OSC.
On Thu, Feb 13, 2014 at 6:50 AM, Jamie Lennox jamielen...@redhat.com
mailto:jamielen...@redhat.com wrote:
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.
I agree, however from a client discovery process point-of-view, you do
not necessarily have an endpoint until after you auth and get a service
catalog anyway. For example, in the specific case of OpenStackClient
Help command output, the commands listed may depend on the desired API
version. To get the endpoints to query for version support still
requires a service catalog so nothing really changes there.
And this doesn't even touch on the SC endpoints that include things like
tenant/project id...
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?
* id: Let's either make this a real semantic version so we can parse and
use the major.minor.patch components (and dump the 'v') or make it an
identifier that matches the URL path component. Right now
* updated: I think it would be a friendly gesture to update this for
unstable changes as the id is likely to not be updated mid-stream.
During debugging I would want to be able to verify exactly which
implementation I was talking to anyway.
So, I'd actually like to extend this a bit differently, and add a micro
version to the API as a normal part of our flows.
https://review.openstack.org/#/c/73090/ is an early sketch of this.
GET /
Content-Type: application/json
Content-Length: 327
Date: Thu, 13 Feb 2014 20:51:48 GMT
{
versions: [
{
status: CURRENT,
updated: 2011-01-21T11:33:21Z,
rev: 2.,
id: v2.0,
links: [
{
href: http://localhost:8774/v2/;,
rel: self
}
]
},
{
status: EXPERIMENTAL,
updated: 2013-07-23T11:33:21Z,
rev: 2.0900,
id: v3.0,
links: [
{
href: http://localhost:8774/v3/;,
rel: self
}
]
}
]
}
And on hitting something under the /v3/ tree:
Content-Type: application/json
X-Osapi-Version: 2.0900
Content-Length: 651
X-Compute-Request-Id: req-6a4ed4f0-07e4-401a-8315-8d114005c6ab
Date: Thu, 13 Feb 2014 20:51:48 GMT
{
version: {
status: EXPERIMENTAL,
updated: 2013-07-23T11:33:21Z,
links: [
{
href: http://localhost:8774/v3/;,
rel: self
},
{
href:
http://docs.openstack.org/api/openstack-compute/3/os-compute-devguide-3.pdf;,
type: application/pdf,
rel: describedby
},
{
href:
http://docs.openstack.org/api/openstack-compute/3/wadl/os-compute-3.wadl;,
type: application/vnd.sun.wadl+xml,
rel: describedby
}
],
rev: 2.0900,
media-types: [
{
base: application/xml,
type: application/vnd.openstack.compute+xml;version=3
},
{
base: application/json,
type: application/vnd.openstack.compute+json;version=3
}
],
id: v3.0
}
}
that would then let us return a pretty fine grained global API version
that included the non breaking backwards compatible changes. Nova is
going to version extensions this time around, but a global increment
would be much better for a consistent view of the world.
-Sean
--
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
Re: [openstack-dev] Version Discovery Standardization
On Thu, 13 Feb 2014 15:54:23 -0500
Sean Dague s...@dague.net wrote:
On 02/13/2014 09:45 AM, Dean Troyer wrote:
FWIW, an early proposal to address this, as well as capability
discovery, still lives
at https://etherpad.openstack.org/p/api-version-discovery-proposal.
I've lost track of where this went, and even which design summit
this is from, but I've been using it as a sanity check for the
discovery bits in OSC.
On Thu, Feb 13, 2014 at 6:50 AM, Jamie Lennox
jamielen...@redhat.com mailto:jamielen...@redhat.com wrote:
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.
I agree, however from a client discovery process point-of-view, you
do not necessarily have an endpoint until after you auth and get a
service catalog anyway. For example, in the specific case of
OpenStackClient Help command output, the commands listed may depend
on the desired API version. To get the endpoints to query for
version support still requires a service catalog so nothing really
changes there.
And this doesn't even touch on the SC endpoints that include things
like tenant/project id...
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?
* id: Let's either make this a real semantic version so we can
parse and use the major.minor.patch components (and dump the 'v')
or make it an identifier that matches the URL path component.
Right now
* updated: I think it would be a friendly gesture to update this for
unstable changes as the id is likely to not be updated mid-stream.
During debugging I would want to be able to verify exactly which
implementation I was talking to anyway.
So, I'd actually like to extend this a bit differently, and add a
micro version to the API as a normal part of our flows.
https://review.openstack.org/#/c/73090/ is an early sketch of this.
GET /
Content-Type: application/json
Content-Length: 327
Date: Thu, 13 Feb 2014 20:51:48 GMT
{
versions: [
{
status: CURRENT,
updated: 2011-01-21T11:33:21Z,
rev: 2.,
id: v2.0,
links: [
{
href: http://localhost:8774/v2/;,
rel: self
}
]
},
{
status: EXPERIMENTAL,
updated: 2013-07-23T11:33:21Z,
rev: 2.0900,
id: v3.0,
links: [
{
href: http://localhost:8774/v3/;,
rel: self
}
]
}
]
}
And on hitting something under the /v3/ tree:
Content-Type: application/json
X-Osapi-Version: 2.0900
So is that a typo there and it should be 3.0900?
Content-Length: 651
X-Compute-Request-Id: req-6a4ed4f0-07e4-401a-8315-8d114005c6ab
Date: Thu, 13 Feb 2014 20:51:48 GMT
{
version: {
status: EXPERIMENTAL,
updated: 2013-07-23T11:33:21Z,
links: [
{
href: http://localhost:8774/v3/;,
rel: self
},
{
href:
http://docs.openstack.org/api/openstack-compute/3/os-compute-devguide-3.pdf;,
type: application/pdf,
rel: describedby
},
{
href:
http://docs.openstack.org/api/openstack-compute/3/wadl/os-compute-3.wadl;,
type: application/vnd.sun.wadl+xml,
rel: describedby
}
],
rev: 2.0900,
media-types: [
{
base: application/xml,
type:
application/vnd.openstack.compute+xml;version=3 },
{
base: application/json,
type:
application/vnd.openstack.compute+json;version=3 }
],
id: v3.0
}
}
that would then let us return a pretty fine grained global API version
that included the non breaking backwards compatible changes. Nova is
going to version extensions this time around, but a global increment
would be much better for a consistent view of the world.
So one question I have around a global version is what happens when we
have the following situation:
- Extension (not core) A is bumped to version 3, global version bumped
to 3.01
- Extension B (not core) is bumped to version 6, global version bumped
to 3.02
but the deployer for $REASONS (perhaps stability/testing/whatever)
really wants to deploy with version 2 of A but
Re: [openstack-dev] Version Discovery Standardization
On 02/13/2014 08:28 PM, Christopher Yeoh wrote:
On Thu, 13 Feb 2014 15:54:23 -0500
Sean Dague s...@dague.net wrote:
On 02/13/2014 09:45 AM, Dean Troyer wrote:
FWIW, an early proposal to address this, as well as capability
discovery, still lives
at https://etherpad.openstack.org/p/api-version-discovery-proposal.
I've lost track of where this went, and even which design summit
this is from, but I've been using it as a sanity check for the
discovery bits in OSC.
On Thu, Feb 13, 2014 at 6:50 AM, Jamie Lennox
jamielen...@redhat.com mailto:jamielen...@redhat.com wrote:
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.
I agree, however from a client discovery process point-of-view, you
do not necessarily have an endpoint until after you auth and get a
service catalog anyway. For example, in the specific case of
OpenStackClient Help command output, the commands listed may depend
on the desired API version. To get the endpoints to query for
version support still requires a service catalog so nothing really
changes there.
And this doesn't even touch on the SC endpoints that include things
like tenant/project id...
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?
* id: Let's either make this a real semantic version so we can
parse and use the major.minor.patch components (and dump the 'v')
or make it an identifier that matches the URL path component.
Right now
* updated: I think it would be a friendly gesture to update this for
unstable changes as the id is likely to not be updated mid-stream.
During debugging I would want to be able to verify exactly which
implementation I was talking to anyway.
So, I'd actually like to extend this a bit differently, and add a
micro version to the API as a normal part of our flows.
https://review.openstack.org/#/c/73090/ is an early sketch of this.
GET /
Content-Type: application/json
Content-Length: 327
Date: Thu, 13 Feb 2014 20:51:48 GMT
{
versions: [
{
status: CURRENT,
updated: 2011-01-21T11:33:21Z,
rev: 2.,
id: v2.0,
links: [
{
href: http://localhost:8774/v2/;,
rel: self
}
]
},
{
status: EXPERIMENTAL,
updated: 2013-07-23T11:33:21Z,
rev: 2.0900,
id: v3.0,
links: [
{
href: http://localhost:8774/v3/;,
rel: self
}
]
}
]
}
And on hitting something under the /v3/ tree:
Content-Type: application/json
X-Osapi-Version: 2.0900
So is that a typo there and it should be 3.0900?
So actually I was thinking about this as a 2.9000 API, as the
pre-release. We can decide it's really 3. instead.
Content-Length: 651
X-Compute-Request-Id: req-6a4ed4f0-07e4-401a-8315-8d114005c6ab
Date: Thu, 13 Feb 2014 20:51:48 GMT
{
version: {
status: EXPERIMENTAL,
updated: 2013-07-23T11:33:21Z,
links: [
{
href: http://localhost:8774/v3/;,
rel: self
},
{
href:
http://docs.openstack.org/api/openstack-compute/3/os-compute-devguide-3.pdf;,
type: application/pdf,
rel: describedby
},
{
href:
http://docs.openstack.org/api/openstack-compute/3/wadl/os-compute-3.wadl;,
type: application/vnd.sun.wadl+xml,
rel: describedby
}
],
rev: 2.0900,
media-types: [
{
base: application/xml,
type:
application/vnd.openstack.compute+xml;version=3 },
{
base: application/json,
type:
application/vnd.openstack.compute+json;version=3 }
],
id: v3.0
}
}
that would then let us return a pretty fine grained global API version
that included the non breaking backwards compatible changes. Nova is
going to version extensions this time around, but a global increment
would be much better for a consistent view of the world.
So one question I have around a global version is what happens when we
have the following situation:
- Extension (not core) A is bumped to version 3, global version bumped
to 3.01
- Extension B (not core) is bumped to version 6, global version bumped
to 3.02
Re: [openstack-dev] Version Discovery Standardization
On Thu, 13 Feb 2014 21:10:01 -0500 Sean Dague s...@dague.net wrote: On 02/13/2014 08:28 PM, Christopher Yeoh wrote: On Thu, 13 Feb 2014 15:54:23 -0500 Sean Dague s...@dague.net wrote: So one question I have around a global version is what happens when we have the following situation: - Extension (not core) A is bumped to version 3, global version bumped to 3.01 - Extension B (not core) is bumped to version 6, global version bumped to 3.02 but the deployer for $REASONS (perhaps stability/testing/whatever) really wants to deploy with version 2 of A but version 6 of B. With versioning just on the extensions individually they're ok, but I don't think there's any real sane way to get a global micro version calculated for this scenario that makes sense to the end user. So there remains a question about extensions vs. global version. I think a big piece of this is anything which is a core extension, So to reduce confusion I've been trying to introduce the nomenclature of everything is a plugin. And then some plugins are compulsory (eg core) and others are optional (extensions) stops getting listed as an extension and instead is part of properly core and using the global version. How extensions impact global version is I think an open question. But Nova OS API is actually really weird if you think about it relative to other cloud APIs (ec2, gce, softlayer). We've defined it not as the Nova API, but as a small core compute API, and many dozens optional features, which every deployer makes decisions on what comes and goes. I agree we need to think through a few things. But I think that if we get to v3, only to have to do a ton more stuff for v4, and take 2 more years to get there, we're in a world of hurt. The current model of API revisions as giant big bangs isn't good for any one. A way to make an API be able to grow over time, in a backwards compatible way, and some mechanism to deprecate and remove a feature over time would be much more advantageous to our consumers. I agree we don't want to avoid another big bang version change for as long as we can. Given that we have extensions (and I know that some people really don't like that) however I'd be a lot more comfortable if this minor global version was only bumped when there were changes to the core plugins or a plugin was added to the core (I don't think we can ever remove them from core within a major version). There should be a high bar on making any changes to core plugins (even though they are backwards compatible). I'm also fine with core plugins not appearing in the /v3/extensions list. Its a simple enough change and agree that it will reduce confusion over interoperability between openstack clouds. Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
