Open Stack

On Mar 12, 2015, at 1:42 PM, Brian Rosmaita <brian.rosmaita at 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

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