Open Stack

> Hi Garbiel
Hi Mrak. ;-)

> This is a bit of a side-track but ... I've been around this project a while now,
> but I admit to still being pretty confused about our approach to API
> versioning. Are extensions really our only way of adding new capabilities to
> an API version in a backwards compatible way?

OpenStack's approach to API versioning has historically had a lot of "continue forward because it's what we know" associated with it. I think most of the PTLs and core devs at this point are together in saying better differentiation of backwards-compatible changes from breaking changes, more minor version bumps, and better definition of what an "extension" means are the future of evolving the APIs. The model of "oh god we can't change anything without rewriting the entire API!" simply has to end.

> And are extensions really our only way of allowing an API capability to be
> optional?

This debate is a current topic on the mailing list and TC. There seems to be a lot of support for "anything that is optional is not core and thereby should be an extensions" but nothing is final there.

> I'd like to see us introducing new API versions a lot less regularly, but still
> being able to add new capabilities (and optional capabilities) in a backwards
> compatible and client-queryable way.

Yep, we're all working towards that. :-)

> Some options for doing that:
> 
>   * We allow minor versions with new features; clients know what
>     features are supported in minor versions and expose capabilities to
>     users based on the queried versions

Yes.

>   * We add a 'GET /capabilities' which returns a document describing
>     which features this endpoints support - a feature could be optional
>     because it was added in a new version or because not all
>     deployments would be configured with it enabled. This would allow
>     clients to be able to query for features, rather than having a
>     hard-coded understanding of which minor versions support which
>     features.

I think we're gonna end up standardizing on "/extensions" because a plurality are less confused by that terminology vs. "capabilities". But that really depends on what the decision is on what an "extension" means. I use the term "capabilities" because it's not coupled to the code-driven idea of an extension in Nova, Cinder, Quantum, etc.

>   * We adopt a more HATEOAS model where a client basically never
>     constructs a URL - everything can be reached via links in the
>     hypertext we return. If an endpoint doesn't support a given
>     feature, it just never includes a link to that feature in the
>     hypertext.

I don't hate HATEOS but I do think it's staggeringly inefficient in the amount of data it requires to be transferred and the number of queries needed for, say, a UI to build on top of it. The upside is that you get a lot of semantic information in the first query or two, but digging deeper can get really costly. The biggest downside to it is it's a complete departure from what we're doing now so it's an even bigger shift.

All in all I think we're on similar tracks.

    - Gabriel