61–70 of 137 posts
Stop writing self-documenting API specs and settle on a hypermedia spec, like Hal or Siren! reply
I actually have no idea why the hal people aren't writing hal specifications for existing services right now--it's not quite as nice as "native" support, but the format supports it, and it would be useful to see what a hal version of the Twitter API looked like, for example.
Yeah, let's do CORBA once again. No thanks.
A key features of a REST API is that is self describable, in a sense, that it has a single entry point from which a generic client can automatically discover available resources and actions. APIs in the given examples are not like this, they require custom clients that are strongly coupled with an application. These are not REST APIs but RPC APIs.
Substitute "XML" for "JSON" and we've now come full circle. 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.)
Substitute "XML" for "JSON" and we've now come full circle. 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.)
I don't think there is a well-known way to self-describe available and required parameters nor any other validation requirements, or am I wrong?
Earlier quoted context omitted.
I don't think there is a well-known way to self-describe available and required parameters nor any other validation requirements, or am I wrong?
I agree. The promise of REST APIs is that will be self describing, but for that benefit to be realized, we need general purpose REST clients that can "discover" everything they need to know given just a root uri. Are there any such clients? And no, web browsers do not count.
You can see links to the clients on the right.
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.
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.
Substitute "XML" for "JSON" and we've now come full circle. 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.)
Hmmmm. Maybe JSON should just take pages from their book instead of reinventing the wheel?
Hmmm....JSON documents (jsonSpec) describing the restful services is the new WSDL, feels like 2002 all over again. I think too many people consume REST APIs in different manners, utilizing different data in unique relations. This is the beauty of it.
Well, to be fair, JSON is at least a lot less verbose than WSDL. So there's that.