"That's not Hypermedia!"
i've been very pleased to see an increasing number of people speaking and writing about the use of
hypermedia in their APIs. in fact, a new wikipedia entry for
Hypermedia API
has recently appeared, too. this renewed focus on a fundamental principle of the Web is a great way
to improve the way we design and build apps for the Web.
but it's important to make sure we're all talking about the same thing. that when we use the word hypermedia we are actually talking about, and showing examples of, hypermedia.
"That's not Hypermedia."
for example, this is not hypermedia:
http://example.org/q1w2e3r4/123
what you see here is just a URL. you know nothing about what it represents, what you can do with that link, or what is at the other end.
this is also not hypermedia:
http://example.org/customers/123
changing some of the characters in the URL does not magicially turn it into hypermedia. even though now (with these new fancy characters) you, as a human, are ready to start making assumptions about what this link represents, what you can do with it, and what's at the other end.
how about a test. what do you think is at the other end?
- a customer record
- a blog entry about the 'customers' product
- a photo of one of the most valuable customers for the last year
and we haven't even started to speculate on what you can do with this URL. can you:
- edit the data?
- remove the record from the system?
- query and or filter the data at the other end of the URL?
and if any of the above are possible, what are the rules for executing the action?
- are there parameters to pass?
- do you pass them in the URL line? the body?
- if you pass them in the body, what are the possible message formats for sending a body?
- what protocol details should be used here? (HTTP? CoAP? which protocol method?)
hopefully, you're getting the picture. a URL alone is nothing but a string. it might be a link to something else, but even that is not assured. the RDF family of technologies often uses URLs as mere identifiers (then they're URIs, actually) that may have nothing at the other end at all.
"This is Hypermedia."
so what does hypermedia look like? it looks like this snippet of Siren:
"actions": [ { "name":"update-customer", "title":"Update Customer", "method":"POST", "href":"http://example.org/customers/123", "type":"application/x-www-form-urlencoded", "fields": [ {"name":"status","type":"hidden","value":"partial"}, {"name":"return","type":"hidden","value":"full"}, {"name":"email","type":"text" }, {"name":"sms","type":"number" } ] } ]
now you can see lots of information about what this URL represents, what you can do with it, and what's at the other end of the link. and you see it all in a form that is machine-readable.
that's hypermedia.
but, what about REST and stuff?
yes, Fielding wrote a 175+ page dissertation which contains a chapter named Representation State Transfer (REST) which is another thing people talk about a lot. and, yes, in that chapter contains a mysterious phrase:
"...hypermedia as the engine of application state."
which some people mangle into an ugly term of art: HATEOAS. but don't get sidetracked. this blog post is about hypermedia, not REST.
You see, REST depends on the use of hypermedia (Roy made that clear back in 2008), but hypermedia does not depend on REST. you can build hypermedia systems without having to create something that matches all of Fielding's REST constraints. and that's an important thing to keep in mind.
so there you have it
when talking about hypermedia, you don't have to be all "REST this..." and "REST that..." and such. just be sure to talk about more than simple URLs. because hypermedia is "all that other stuff" we need in order to get work done on the web. Leonard Richardson says it really well in the book RESTful Web APIs:
"Hypermedia connects resources to each other, and describes their capabilities in machine-readable ways." and "Hypermedia is a way for the server to tell the client what HTTP requests the client might want to make in the future."