He states very explicitly that his examples weren't any kind of standard, as one doesn't truly exist at that level.

I think the point he was trying to get across, and really what a lot of people who are advocates for REST are trying to accomplish, is that in a fully realized model computers would be able to understand how to talk to each other to get information and update resource states without the need for human intervention.

Clearly we are a long way from that goal, but I think it's still something worth talking about.

Whilst the notion of "computers talking to each other without human intervention" sounds like a utopian ideal, I think his method is a recipe for disaster.

The domain of possible consequences of changing protocols and semantics on the fly is hugely complex. What about testing? Are we advocating that we change live systems without tests?

The author writes: "Level 3 introduces discoverability, providing a way of making a protocol more self-documenting."

I reply: The same way good design separates presentation, logic and data, it follows that good protocols separate data from documentation.

> possible consequences of changing protocols and semantics on the fly is hugely complex

Except when you assume that you're reading the semantics from each and every response. It introduces some complexity to how clients need to accept responses. However, once that part is done the changing protocol and semantics should not disrupt the system.

And testing? That's not a very difficult component to test. Throw a few different 'schemas' at the HTTP client response module and then feel safe to drop that into your application. I believe you're imagining a system that is more highly coupled to the response schema. This approach is meant to remove that coupling entirely (well, except for a base uri :))

I agree that embedding <link />'s into the response is a violation of a separation of concerns. They should probably be separated in some way (HTTP headers?). However, there are precious few examples of this in the wild and we may see some creative ways to separate these (I just hope we don't go the way of XML to have a different resource to specify schema).

I don't know if it is true that that is what REST advocates are trying to accomplish. If you want to remove the human than SOAP and WSDL have gone a long way towards that goal. I always viewed REST as the opposite of that, make things simple so the developer is able to easily manipulate the data as he sees fit.

I understood it to be decoupling the what from the how. In this case, it decoupled knowing that you needed to book an appointment from the URI that lets you do that.

If I already what what I want to do, but I allow a service to tell me how to do it, me and the service have a looser coupling. If the service decides to change how I accomplish the task, then I should seamlessly adapt.

But, in practice, how often does a service change an URI only, without changing the input or output parameters (causing you to have to re-factor your client anyway)?

Often merely moving from the dev environment to the release environment changes the URIs. Sure, you could try to minimize the part that changes between environments and teach all your clients to form correct URIs between environments, but it's still coupling. And dev/prod is hardly the only thing people find themselves adjusting in URIs; it was just an example.

One example, if you move domains, all you'd need to do is redirect the single entry point URL to the new one without having to force clients to change anything and with having to redirect every single API request.

You can also allow other sites to implement the same API and clients would only have to select a different entry point. Look at AtomPub for instance.

I want to agree with you, "Hypermedia Controls" seems a bit odd to me, but I don't think it's such a new concept when it comes to REST.

This is from Roy Fielding's blog: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

... all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

He's explicate in that a REST system must return options for further action. Links. This is the default behavior of the web, request a page get a page full of links. Martin Fowler is just describing a system that uses a hypermedia implementation other than html.

The benefit to this is that you don't need out-of-band information to interact with a new server you run into.

Look at it this way. If I'm at a REPL, and I have this:

    o = SomeObjectOfUnknownCapabilities.instance

then I can do this:

    p o.methods

...and see what I can call. The method names give me no guarantee as to what the methods will actually do ("slice" could return a subset of data, or cut a pie), but once I have the verbs, in either case, I can experiment. That's the important bit here—discoverability isn't about knowing what new things do right off the bat, because that's impossible unless there's a finite set of things you can do; discoverability is simply about being told the affordances, so you can manipulate them and observe the results.

The idea is that the client code will search for the link element whose rel attribute is equal to the known value the client is looking for, and then get the uri attribute for the request. In other words, the client knows the name of the uri for the functionality it wants, but it doesn't have to know the uri. This allows the uris to change if needed.

It's like using constants instead of literals in your code. If the literal value has to change you only have to change the constant definition, not every place in the code where the value is used.

I agree. If he truly wants to create a system that can be updated only from the server side he needs some sort of human readable description for the control. displayAs = "Book Appointment" for example in this case.