Re: [openstack-dev] [Glance] Experimental API
On Mar 12, 2015, at 1:42 PM, Brian Rosmaita wrote: > I don't know how elaborate we want to get here, but Everett Toews had an > interesting suggestion in the openstack-api channel. It would go something > like this: > > (1) User gets "/x1/search" endpoint from service catalog > (2) User does some request against /x1/search My apologies, I should have been a bit more specific. I actually meant put a version in some header *instead* of putting any version info in the URL. But I realize that Glance already uses the /vN/ style in its URLs. Given the info on header’s below, an /xN/ style would not be necessary. > (3) User receives 400 with an error message like: > This is an experimental API. > You must include the following header with your request: >x-openstack-api-status: acknowledged > By using this header, you acknowledge that while we think this API is > pretty solid, we reserve the right to make breaking changes as we analyze > usage patterns and API consumer comments during the experimental period. > Please send comments to the OpenStack Future Development Mailing List with > the subject "[Glance] x1 API". > To subscribe to the mailing list: > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > (4) User makes all subsequent requests including the > x-openstack-api-status header I don’t think you’d necessarily need to invent a new header. You could reuse something semantically similar to Nova’s X-OpenStack-Nova-API-Version [1], which can include an "experimental" tag. The experimental nature of the API would need to be documented thoroughly somewhere. And how to work with it by including the “experimental” tag in the X-OpenStack-Glance-API-Version header. It would be best if the error message just linked to that documentation. Everett [1] http://specs.openstack.org/openstack/nova-specs/specs/kilo/approved/api-microversions.html#client-interaction __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Glance] Experimental API
This would require some changes to how python-glanceclient parses versions. Even if the keystone catalog has a version string in it (which typically is not the case for glance) the version parsing in common/utils only recognizes version strings beginning with 'v'. Would it be sensible to add clients/x1 (that might largely inherit from clients/v2 code)? Or alter glanceclient/client to treat an 'x' version as the same as 'v' (in which case maybe 'use /x2')? Steve On 3/12/15, 1:42 PM, "Brian Rosmaita" wrote: >I don't know how elaborate we want to get here, but Everett Toews had an >interesting suggestion in the openstack-api channel. It would go something >like this: > >(1) User gets "/x1/search" endpoint from service catalog >(2) User does some request against /x1/search >(3) User receives 400 with an error message like: >This is an experimental API. >You must include the following header with your request: >x-openstack-api-status: acknowledged >By using this header, you acknowledge that while we think this API is >pretty solid, we reserve the right to make breaking changes as we analyze >usage patterns and API consumer comments during the experimental period. >Please send comments to the OpenStack Future Development Mailing List with >the subject "[Glance] x1 API". >To subscribe to the mailing list: >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >(4) User makes all subsequent requests including the >x-openstack-api-status header > >If we did something like that, my conscience would be completely clean if >we wound up introducing a breaking change. > > >On 3/12/15, 1:19 PM, "Sampath, Lakshmi" wrote: > >>We had a discussion with API WG today about what it means to be an >>"EXPERIMENTAL API" and here's the takeway from that discussion. >> >>- API's can be experimental, but mark it clearly in the docs as such >>- Experimental means a breaking change may be introduced >>- Use /x1/ instead of /v1/ in the endpoint. >> >>Thoughts/Suggestions? >> >> >>Thanks >>Lakshmi. > > >__ >OpenStack Development Mailing List (not for usage questions) >Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Glance] Experimental API
On Thu, Mar 12, 2015 at 1:42 PM, Brian Rosmaita < brian.rosma...@rackspace.com> wrote: > I don't know how elaborate we want to get here, but Everett Toews had an > interesting suggestion in the openstack-api channel. It would go something > like this: > > (1) User gets "/x1/search" endpoint from service catalog > (2) User does some request against /x1/search > (3) User receives 400 with an error message like: > This is an experimental API. > You must include the following header with your request: > x-openstack-api-status: acknowledged > By using this header, you acknowledge that while we think this API is > pretty solid, we reserve the right to make breaking changes as we analyze > usage patterns and API consumer comments during the experimental period. > Please send comments to the OpenStack Future Development Mailing List with > the subject "[Glance] x1 API". > To subscribe to the mailing list: > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > (4) User makes all subsequent requests including the > x-openstack-api-status header > What keeps me, as a shady client, from just including x-openstack-api-status from the start? and how is that different from intentionally selecting an EXPERIEMNTAL endpoint form the service catalog? > If we did something like that, my conscience would be completely clean if > we wound up introducing a breaking change. You also could do proper versioning even though it is experimental. That'll help prove the version handling is working properly too. As a dev trying to get early use on an experimental API, I still need to be able to detect when changes occur. dt -- Dean Troyer dtro...@gmail.com __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Glance] Experimental API
On 03/12/2015 01:19 PM, Sampath, Lakshmi wrote: We had a discussion with API WG today about what it means to be an "EXPERIMENTAL API" and here's the takeway from that discussion. All experimental means with regards to an API is "we reserve the right to completely abandon this or change it in backwards compatible ways". - API's can be experimental, but mark it clearly in the docs as such Sure. - Experimental means a breaking change may be introduced - Use /x1/ instead of /v1/ in the endpoint. -1 on using "x1". I don't see the point, honestly. Code (in clients) doesn't know or care whether there is a difference in compatibility guarantee between "x1" and "v1". Humans do. Leave it up to the documentation to mark some API as experimental and just use /v1 Best, -jay Thoughts/Suggestions? Thanks Lakshmi. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Glance] Experimental API
I don't know how elaborate we want to get here, but Everett Toews had an interesting suggestion in the openstack-api channel. It would go something like this: (1) User gets "/x1/search" endpoint from service catalog (2) User does some request against /x1/search (3) User receives 400 with an error message like: This is an experimental API. You must include the following header with your request: x-openstack-api-status: acknowledged By using this header, you acknowledge that while we think this API is pretty solid, we reserve the right to make breaking changes as we analyze usage patterns and API consumer comments during the experimental period. Please send comments to the OpenStack Future Development Mailing List with the subject "[Glance] x1 API". To subscribe to the mailing list: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev (4) User makes all subsequent requests including the x-openstack-api-status header If we did something like that, my conscience would be completely clean if we wound up introducing a breaking change. On 3/12/15, 1:19 PM, "Sampath, Lakshmi" wrote: >We had a discussion with API WG today about what it means to be an >"EXPERIMENTAL API" and here's the takeway from that discussion. > >- API's can be experimental, but mark it clearly in the docs as such >- Experimental means a breaking change may be introduced >- Use /x1/ instead of /v1/ in the endpoint. > >Thoughts/Suggestions? > > >Thanks >Lakshmi. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Glance] Experimental API
Thanks Lakshmi, that's useful. So, we want to release Artifacts API in Kilo as experimental. We do need some early adopters to begin working with it (the initial interest was from Heat and Murano projects, and the OVA/OVF initiative for Images as well) in the next cycle and provide some feedback on the API and its usefulness, so we may take this feedback into account before releasing the stable version of API with L. I've talked to Murano folks, they are ok with that plan, some feedback from Heat and OVA teams would be great as well. Anyways, we will not break the compatibility without serious reasons for that, and we will collaborate with any early adopters about any such breaking changes. -- Regards, Alexander Tivelkov On Thu, Mar 12, 2015 at 8:19 PM, Sampath, Lakshmi wrote: > We had a discussion with API WG today about what it means to be an > "EXPERIMENTAL API" and here's the takeway from that discussion. > > - API's can be experimental, but mark it clearly in the docs as such > - Experimental means a breaking change may be introduced > - Use /x1/ instead of /v1/ in the endpoint. > > Thoughts/Suggestions? > > > Thanks > Lakshmi. > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [Glance] Experimental API
We had a discussion with API WG today about what it means to be an "EXPERIMENTAL API" and here's the takeway from that discussion. - API's can be experimental, but mark it clearly in the docs as such - Experimental means a breaking change may be introduced - Use /x1/ instead of /v1/ in the endpoint. Thoughts/Suggestions? Thanks Lakshmi. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
