Re: [openstack-dev] [api-wg] Question about 'OpenStack-API-Version' header
On Mon, Apr 17, 2017 at 10:22:16AM +0100, Chris Dent wrote: > On Fri, 14 Apr 2017, Qiming Teng wrote: > > >According to the microversion specification [1], the > >'OpenStack-API-Version' header is optional. When it is omitted, the > >server should act as if the minimum supported version was specified. > > That's correct. > > >Recently, we have received some complaints from users that for new APIs > >added, we should state that the header is required. The new APIs are > >valid only after a specific microversion. If the 'OpenStack-APi-Version' > >header is missing, our server returns a 404 resource not found error. > >It is confusing. > > There's a bit of a circle here. If you're using microversions and you > add a new feature at, for example, version 2.24 then yes, you must > include the header with a microversion of 2.24 or beyond in order to > use that feature. This is aligned with the "opt-in" nature of > microversions and changes to the service. > > If the new microversion is adding a new URL, then a 404 response is > correct when that microversion has not been selected. > > So, yes, it is the case that when adding a new URL to a service that > is already supporting microversions, the header is required. That's > pretty much how microversions work and the service documentation > should indicate that. This answered my question pretty well. Since we are using api-ref to document the service API, each resource URL is documented separately. For newly added URL, following micro-version guideline, we are supposed to state that the micro-version header is required. This was the part that is missing from the referenced guideline. Thank you, Chris. - Qiming > Is there a different workflow that you (or the people complaining) > have in mind that could work better? Is there something that could > or should be clarified to make this more clear? > > -- > Chris Dent ¯\_(ツ)_/¯ https://anticdent.org/ > freenode: cdent tw: @anticdent > __ > 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] [api-wg] Question about 'OpenStack-API-Version' header
On Fri, 14 Apr 2017, Qiming Teng wrote: According to the microversion specification [1], the 'OpenStack-API-Version' header is optional. When it is omitted, the server should act as if the minimum supported version was specified. That's correct. Recently, we have received some complaints from users that for new APIs added, we should state that the header is required. The new APIs are valid only after a specific microversion. If the 'OpenStack-APi-Version' header is missing, our server returns a 404 resource not found error. It is confusing. There's a bit of a circle here. If you're using microversions and you add a new feature at, for example, version 2.24 then yes, you must include the header with a microversion of 2.24 or beyond in order to use that feature. This is aligned with the "opt-in" nature of microversions and changes to the service. If the new microversion is adding a new URL, then a 404 response is correct when that microversion has not been selected. So, yes, it is the case that when adding a new URL to a service that is already supporting microversions, the header is required. That's pretty much how microversions work and the service documentation should indicate that. Is there a different workflow that you (or the people complaining) have in mind that could work better? Is there something that could or should be clarified to make this more clear? -- Chris Dent ¯\_(ツ)_/¯ https://anticdent.org/ freenode: cdent tw: @anticdent__ 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] [api-wg] Question about 'OpenStack-API-Version' header
According to the microversion specification [1], the 'OpenStack-API-Version' header is optional. When it is omitted, the server should act as if the minimum supported version was specified. Recently, we have received some complaints from users that for new APIs added, we should state that the header is required. The new APIs are valid only after a specific microversion. If the 'OpenStack-APi-Version' header is missing, our server returns a 404 resource not found error. It is confusing. So ... I'm reaching out to you for some comments and suggestions. Are there any best practices on this? - Qiming [1] https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html __ 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
