[steveklabnik]

You're forgetting form-style affordance. For example, if you were using HTML as your media type, the equivalent of the first example would be

  <form method="get" action="/me">
    <input type="text" name="access_token" />
    <input type="text" name="fields" />
  </form>

> AFAIK you're still going to want some marshaling to/from host language.

Actually, you explicitly _don't_ want this. That's what hypermedia APIs are trying to remove.

[stephen]

We're replying to each other in separate comment threads :-), but this input form is still coupling--you can't add/remove/change the access_tokens/fields without clients breaking. Humans can handle that. Software can't.

That's why I think hypermedia makes all sorts of sense for explaining why the www is awesome--it change deal, users will adapt. But IMO it falls flat as some new paradigm for building client/server systems.

> Actually, you explicitly _don't_ want this. That's what hypermedia APIs are trying to remove.

Hm? I am skeptical...any links/explanations?

[steveklabnik]

Haha! Ping-pong!

> But IMO it falls flat as some new paradigm for building client/server systems.

I know of one company which you've absolutely heard of who has a 30-person team building a hypermedia API. They haven't talked about it publicly because they see it as a strategic advantage.

This year will be the year of code and examples; last time I was in San Fransisco, 5 different startups came up to me and told me that hypermedia is solving their problems. Expect to see more of this going on soon.

> Hm? I am skeptical...any links/explanations?

Mike Amundsen's "Building Hypermedia APIs in HTML5 and Node" has a pretty big section on this, and my book has a section entitled "APIs should expose workflows."

I previously commented more about it here: http://news.ycombinator.com/item?id=4951477

RPC APIs expose functions, SOAP/"REST" APIs expose objects, hypermedia APIs expose processes.