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: [email protected]?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
