[ms123]

Hypermedia APIs are an approach to solve this problem. It essentially does what you did, and add some other benefits like de-coupling URIs.

[stephen]

Really? Seems to me like Hypermedia APIs should move the problem from the wire protocol to the application protocol?

Hypermedia says "oh yeah, here's some markup, look there are URIs in it". For a human user, we're like "cool, I'll try and click these, see what they do".

But software is going to want "um...okay, how to I parse this markup, and how do I generate the submissions you want? And, okay, you can change URIs, but please don't change anything else about that operation, or I will break completely. That's right, we're not really decoupled."

So, even with hypermedia APIs, AFAIK you're still going to want some marshaling to/from host language. ...and so you're back to having a spec, and coupling, you've just moved it around.

(Rant on coupling, people seem to think it's always bad and you can make it go away. Reality: you can't make it go away, and sometimes just accepting it directly is a whole lot simpler than deceiving ourselves about it's existence by over-applying abstractions.)

[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.