To paraphrase the OP, "Since so many APIs can be described in similar terms, why don't we have some sort of standard that one can look at to identify how to use the API instead of letting the API speak for itself?"
When you start going down this track, you're not only making things complicated on the client's end of things. On the server side, you're having to maintain two things for the API now. First: the ruleset, ensuring it's 100% to spec lest a client fail. Second: the code generating the response in the first place.
I've built clients and servers for both RESTful and SOAPy APIs and I can say I would take REST any day.
You can see links to the clients on the right.
OPTIONS /somePath?
https://github.com/caseysoftware/web2project-slim
But one of the things I did a little differently is that instead of writing the code and then the docs separately, I pass the validation information from the object itself.. so the API layer doesn't have to know any of it in advance. It can pass that along to the end clients.
I'm not convinced this is the solution but it mostly works for now and would love any & all feedback.
My next proof of concept will be to use Javascript to retrieve the required fields and decorate a simple html form.
REST means more than just GET, POST, PUT, DELETE.
Some may make the excuse that call OPTIONS /path isn't straightforward, but I have no clue how you could get more obvious than that.
I really wish there was a DESCRIBE verb that would return a structure of what is expected to be received/sent.
Then microformats could spring up around datatypes returned by DESCRIBE. This is of course very XML.
Edit: This would also allow for automatic discovery of new APIs.
...
> ... XML is ugly. JSON is nice since it's human-readable and light.
???
XML:
<list>
<items>
<item>Milk</item>
<item>Eggs</item>
<item>Bread</item>
<item>Butter</item>
</items>
</list>
JSON: {
"list": {
"items": [
"Milk",
"Eggs",
"Bread",
"Butter"
]
}
}
I don't know that either one is particularly close to the way I'd write down a list in real life, to be honest. This is a pretty trivial sample, and neither is especially hard to read/parse by a human. But the JSON still looks closer to line-noise to me. :-)
The point about REST is that it is self-describing. And ideally should be using the same URIs as the version people clicking around in Firefox or Chrome see. The API is just the XML or JSON or whatever is flavour of the week version of the HTML version.
(Or we could use embedded data—microformats, microdata, RDFa—and get rid of that distinction.)