[michaelw]

Sigh. This is optimizing for the wrong problem.

Stop creating REST APIs that are only level 1 or 2 (see http://martinfowler.com/articles/richardsonMaturityModel.htm... ).

Start writing HATEOS systems where the client is coupled to the semantic rather than the syntax.

Machine parseable interface descriptions might get rid of some boilerplate but it doesn't make for a more robust client-server relationship.

[stephen]

Yes, URIs in the response sounds amazingly cool, but it won't change anything.

The inline URLs of the web work because the consumers are humans who can deal with changes (more than just trivial URL changes, like added, removed features) and now click on this button or that button.

Software isn't that flexible, so it will be just as coupled as it is today--you're just moving the coupling around.

So this idea of a "robust client-server relationship" is a pipe dream IMO.

[Flenser]

With some conventions how the api is structured it's possible to have loose coupling the between client and server. This video demonstrates how it is possible to make changes in structure of the API that the client detects automatically:

http://oredev.org/2010/sessions/hypermedia-apis

And he's release a Java library for creating such a client:

https://github.com/cimlabs/hypermedia-client-java

[steveklabnik]

I've built these kinds of things before: http://words.steveklabnik.com/i-invented-hypermedia-apis-by-...

[stephen]

Not saying that system doesn't sound cool, but my point about hypermedia APIs is that when you serve back:

<link href="http://example.com/low.rss rel="podcast_url" />

You've moved the coupling from "look at URL xyz" to "look for rel podcast_url". Okay, yes, you can now change the URL, that's cool, but I assert that's relatively trivial. You can't truly add/remove new functionality (or break existing contracts, like "look for rel=podcast_url") that some omnipotent client would suddenly start taking advantage of.

IMO this omnipotent realization/utilization of new/changed features is what hypermedia advocates get all excited about, without realizing that humans are really the only ones that can deal with that level of (true) decoupling.

[steveklabnik]

The important part is that this is all documented in the media type. Of course, computers aren't able to just figure out what's up, that's why it's agreed upon beforehand.

> You can't truly add/remove new functionality

You can absolutely add new functionality, because rule #1 of clients that work this way is 'ignore things you don't understand.' Removal will obviously break things, so it's important to handle this in the appropriate way.

I guess ultimately my point is that these kinds of APIs are significantly different, and come with a very different set of constraints/goals/implementation details. It's like you're saying "well, I don't have a full list of function calls I can make!" because you're used to SOAP where there's a WSDL and 'RESTful' APIs don't have description documents. Of course! It's a different architecture!

[steveklabnik]

As one of my friends on twitter said, "Yes, people won't put their URIs in responses, so let's just put them in this other, totally unrelated file."

[algorithmmonkey]

true story. we could do worse than moving toward something like: http://stateless.co/hal_specification.html.

[robbles]

Can you give an example of an acceptable implementation of a HATEOAS REST API (wow, that's a lot of letters) with an associated client that actually uses it?

My experience has been that you can't communicate much through HATEOAS that's actually beneficial to a human programmer writing a client. Sure, you can add all the hypermedia links you want in your API responses, but how does that make writing a client easier? Wouldn't it just be helpful to crawlers?

Not trying to put down the idea - I want to believe, but I just haven't seen any obvious examples using it in the real world yet.

[steveklabnik]

> (wow, that's a lot of letters)

We're all calling these "hypermedia APIs" these days.

> with an associated client that actually uses it?

I have written a toy client here: https://gist.github.com/steveklabnik/2187514

You can run it against this site, written in node: http://alps-microblog.herokuapp.com/

Or this site, written in Rails: https://rstat.us/

It (should, I haven't tried it in a long while) work with both just fine. They both use the ALPS microblogging spec. yay generic clients!

As for people who have 'more real' ones: GitHub, Twilio (partially, more in the future), Balanced Payments (YC W11, iirc), Comcast (though that's internal :() Netflix has aspects, FoxyCart.

This year will be the year of examples.

[robbles]

Interesting. I didn't realize that there were specs like ALPS for defining how to implement this kind of thing. Isn't it still a little difficult to do this for APIs that don't neatly fit into some kind of generic profile (e.g. microblogging)?

[steveklabnik]

There's a few different ways to go about things, but every app has some kind of domain. If you're the first, then you can define how it works. :)

Mike Amundsen's terribly named but amazingly well written 'Building Hypermedia APIs in HTML5 and Node' is a really thorough examination of this topic.