[Openstack] Compute API Versioning
btaylor at rackspace.com
Wed Dec 21 18:39:17 UTC 2011
On 12/21/2011 05:56 AM, Mark McLoughlin wrote:
> On Tue, 2011-12-20 at 10:35 -0500, Brian Waldon wrote:
> - Versioning is important, but I'd prefer us to place more emphasis
> on how to design the API such that we can continue to expand the
> API in compatible ways for a decent period without introducing a
> new major version e.g.
> - capability discovery - clients should not assume the API
> supports a given feature, but should query for its availability
> at runtime
> - opaque URI structure - by requiring clients to navigate links
> in the hypertext documents returned by the server, you can
> change things around without breaking well-written clients.
> Basically, a good rule is that a client should never need to
> construct a URI
I agree. In fact, I think it actually accomplishes your previous point.
It comes down to using media types and link relations well, so that a
client is told the semantics of how to find the link path to the things
they want and if no such path exists within the semantics they
understand, then the feature in question isn't part of their world.
> - versioning of resources - if we versioned individual resources,
> we could introduce a new incompatible version of a single
> resource without affecting users of other resources.
I'm not sure I understand this last point exactly. Individual resources
exist or don't, they don't have versions. Resource *types* can evolve,
but if we do this correctly, as you want above, it should be
discoverable. When we create a resource hierarchy and use the URI path,
we do so solely for the benefit of the server to locate its resources.
Clients always want to latch on to this and do RPC style integration,
but we should discourage it. The server has to know how to interpret its
own URI namespace, so that when it sees a URI like
http://example.api.com/widgets/123 that it can figure out that we are
talking about a widget and grab #123. So we probably don't want to mix
coconuts and widgets under the http://example.api.com/widgets path, for
our own sanity implementers of the server. But that's our choice as
server designers, not something that HTTP or REST mandates. Clients have
no right to rely on it unless we tell them they within a specific
If widget/123 relates to gadget/789, but widget/456 has no gadget, the
client will "discover" this fact because the former will have a gadget
link like http://example.api.com/gadget/789 but the latter won't. If we
add gadgets in the 2013 release, clients who want to leverage this have
to do two things: they have to understand the new app/gadgets media type
and they have to understand how we added links to gadgets from widgets
so they can navigate to them. The point is gadget agnostic clients that
care about widgets should still work fine and shouldn't have to change.
> - The big argument for URI based versioning is that not all clients
> (e.g. browsers) can participate in content type negotiation. I'm
> not convinced that's a huge issue, though.
This has been debated quite a bit. I think the consensus seems to be
emerging that direct use of a browser to introspect our APIs is
something we are willing to sacrifice to get simplicity in our APIs. So
basically, if it simplifies our APIs, I'm happy saying "we only support
clients that can do proper content negotiation" and leaving it up to UI
developers to deal with use cases that target viewing raw payloads in
browsers if they think it's useful.
More information about the Openstack