Thursday, April 29, 2010

Back to HATEOS and APIs

REST-like discoverability could also be a boon for some services. What if Twitter provided something like this along with a tweet’s JSON?

{  "actions": {  "Retweet" : { "method":"POST", url:"/1/statuses/retweet/12345.json" },  "Delete" : { "method":"DELETE", url:"/1/statuses/destroy/12345.json" },  "Report Spam" : { "method":"POST", url:"/1/statuses/retweet/12345.json", params:{"id":12345} }  }  }

YES. I had talked about this in the HATEOS post that I wrote a while back. Right now, only html is self-discovering. XML and JSON docs should also have self-documented descriptions of next actions a client can take. That way, you'd cut down on the amount of documentation requires to understand or use an API.

One good point brought up in the comments in that last point was that if I had internal links, a client is likely to know what to do with what it gets back. But if I linked outside of my service, say, how would I understand the schema? There's no standardized set of tags for geolocation data, like there is hypertext data.

Until we get standard media types for specific kinds of web applications, I'm afraid we're stuck.

Posted via web from The Web and all that Jazz

1 comment:

  1. I don't think its as bad as all that.

    Certainly standardization will make it easier to consume data but standardization does not need to precede utility. Common ad hoc media types will work in the interim and once they become sufficiently common they can be standardized. This also makes for a better standard since the utility of the implementation is already established.

    I'm a big believer in gratuitously creating new media types. And of handling multiple media types and performing content negotiation via the Accepts header.

    I would submit that there _is_ a standard media type that would work wonderfully well in this situation.

    Topic Maps. cf.

    They're a little (maybe a lot) abstract to get you're head around initially (they have their origin in knowledge management) but they are ideal for creating a generalized, self coding (honestly) client for basically any application you can think of.

    And I'm 90% confident that today, you can create a standard, well understood representation of a geographic location with a topic map.