Getting hyper about hypermedia APIs

> Hypermedia hype has always struck me as parallel to the "semantic web" nonsense from the late 90s.

That's funny, because DHH's proud ignorance about hypermedia strikes me as parallel to the usual proud ignorance about the semantic web.

Your first 2 paragraphs don't actually say anything, they just signal your allegiances.

You still need to know the meaning of each link relation, that is true. When hypermedia advocates gloss over this, or imply that clients will just magically know what to do with all the data and links coming from the API entry point, it annoys me. It's dishonest.

But what you gain from link relations is worth advocating for:

* Link relations can be standardized across APIs. This opens the door for clients to infer functionality when presented with links it recognizes. There is a list of currently standardized link rels here: http://www.iana.org/assignments/link-relations/link-relation...

* Link relations provide an abstraction layer over the implementation, which may change. They're not unlike an API in and of themselves. As long as the 'photos' link relation does not change, it can point to whatever URL it wants, and that URL or URL structure can change over time without damage to the client.

* Using exclusively URLs to identify resources, as opposed to making the client memorize how to take any ID and map it into a URL, frees up an API to refer to resources outside its scope. That is big, enabling multiple APIs to connect as a proper ecosystem, with outgoing and incoming links. We can't do that today.

Your applicaiton's link relations should be URLs. This means that you can expose each bit of documentation for each rel at their URL. So every time you see a link in a hal+json document, you can follow the _rel's_ URL, and fetch the documentation for it.. that turns out to make the API very easily discoverable, and gives you a way to model/manage your API's documentation in a consistent way.

You can actually see what that looks like in practice here (click one of the book icons on one of the links on the left):

http://haltalk.herokuapp.com

One neat trick that I think is worth adding to the discussion: URL templates.

Returning URL templates as part of your API response can give you the benefits of having a clean way to access sub-resources, without the headaches and bloat of having to enumerate every possible desired sub-URL.

For example, in DocumentCloud, a document's canonical representation has a unique URL for the content of every page as plain text, and as an image, in several different rendered sizes. Instead of doing something silly like this:

    resources: {
      text: [
        "http://www.documentcloud.org/documents/1/pages/page-1.txt",
        "http://www.documentcloud.org/documents/1/pages/page-2.txt",
        "http://www.documentcloud.org/documents/1/pages/page-3.txt",
        ...
      ],
      largeImages: [
        "http://www.documentcloud.org/documents/1/images/page-1-large.png",
        ...
      ],
      thumbnailImages: [
        "http://www.documentcloud.org/documents/1/images/page-1-thumb.jpg",
        ...
      ]
    },
    ...

... where you might have 5,000 pages in a document, you can imagine how unacceptably large that response might become. Instead, a single URL template can do the work. (http://tools.ietf.org/html/rfc6570) The spec has a whole bunch of goodies in it, but we just need the most basic interpolation feature for this case (real example, you may have to scroll sideways to see the complete URL):

    "pages": 5058,
    "resources": {
      "page": {
        "image": "http://s3.documentcloud.org/documents/21939/pages/sotomayor-s-senate-questionnaire-p{page}-{size}.gif",
        "text": "http://www.documentcloud.org/documents/21939/pages/sotomayor-s-senate-questionnaire-p{page}.txt"
      },
      "pdf": "http://s3.documentcloud.org/documents/21939/sotomayor-s-senate-questionnaire.pdf",
      "published_url": "http://documents.nytimes.com/sotomayor-s-senate-questionnaire",
      "related_article": "http://www.nytimes.com/2009/06/05/us/politics/05court.html",
      "search": "http://www.documentcloud.org/documents/21939/search.json?q={query}",
      "text": "http://s3.documentcloud.org/documents/21939/sotomayor-s-senate-questionnaire.txt",
      "thumbnail": "http://s3.documentcloud.org/documents/21939/pages/sotomayor-s-senate-questionnaire-p1-thumbnail.gif"
    },

Basically, all of the simple URLs a Viewer might need to use in order to browse the document, search the text, and view related resources. In the past, when we've needed to change or expand the number of resources (adding HTTPs-only support, changing the URLs at which the page images are stored, or adding larger sizes of page images), it's been relatively easy to do, without breaking the viewers, or invaliding previously-valid JSON representations of the document. Here's the complete link to the above:

http://www.documentcloud.org/documents/21939-sotomayor-s-sen...

AKA "not REST in any way, shape or form" AKA "good old RPC over HTTP".