Hypermedia APIs are an approach to solve this problem. It essentially does what you did, and add some other benefits like de-coupling URIs.
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.)
<form method="get" action="/me">
<input type="text" name="access_token" />
<input type="text" name="fields" />
</form>
Actually, you explicitly _don't_ want this. That's what hypermedia APIs are trying to remove.
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?
> 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.