Re: URI design, part 2

On Sat, Dec 1, 2012 at 8:30 AM, Erik Mogensen <[email protected]> wrote:

> But this is still not enough to determine if a system adheres to the
> constraints: For even though the server provides such hypermedia controls,
> media types and does everything "by the book", it is still up to the
> *client* to actually *use* these hypermedia controls.  In fact it is up to
> the author of the agent itself.
>
> If you write code in the client that hard wires a button called "cancel"
> to the "POST /orders/1/cancel" HTTP request then the client isn't really
> honouring the hypermedia controls laid out above.  If, however, it _soft
> wires_ the same button _because_ of the hypermedia control above, then
> you're doing it "more right" I would say.  The point is that the client
> should be written in such a way that it uses _only_ the hypermedia controls
> that it receives at run-time.
>

This seems like a really important point. As I started reading about
hypermedia APIs, the authors seemed to be evangelizing the benefit that
server programmers could change URIs as requirements evolved. But it seems
you can only realize that benefit easily if you can guarantee that all your
clients use the hypermedia controls, or that you force the issue by
breaking clients that aren't honoring that agreement. Hypermedia APIs seem
to raise the expectations on client programmers more than for server
programmers.

As a server programmer, I'm interested to find great examples of hypermedia
APIs (and ecosystems, documentation, etc.) that help their client
programmers do the right thing.

Even then, if you can't prevent client developers from "deep linking" into
your API, how do you handle breaking changes for those clients?

-- 
Matt McClure
http://www.matthewlmcclure.com
http://www.mapmyfitness.com/profile/matthewlmcclure