Open Stack

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.
This!
>
>        - 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 
endpoint domain.

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.