
Father of HTTP and REST: REST APIs must be hypertext-driven - inklesspen
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
======
inklesspen
I'm still trying to figure out what he means here...

~~~
smoody
There was a link to an article posted yesterday or the day before on HN that
attempted to interpret the original article. Here's the link:

[http://www.25hoursaday.com/weblog/2008/10/24/RESTAPIDesignIn...](http://www.25hoursaday.com/weblog/2008/10/24/RESTAPIDesignInventMediaTypesNotProtocolsAndUnderstandTheImportanceOfHyperlinks.aspx)

I have to admit it's still a bit confusing to me. However, look at this
snippet extracted from a comment by the author of the article you provided:

"A truly RESTful API looks like hypertext. Every addressable unit of
information carries an address, either explicitly (e.g., link and id
attributes) or implicitly (e.g., derived from the media type definition and
representation structure). Query results are represented by a list of links
with summary information, not by arrays of object representations (query is
not a substitute for identification of resources)."

And this snippet from the second:

"The latest drafts of the OpenSocial specification have a great example of how
a service can use existing technologies such as URI templates to make even
complicated URL structures to be flexible and discoverable without having to
force every client and service to hardcode a specific URL structure."

This, to me, states that a restful api should implement api discoverability
and give people a method to generate URI for any api call without hard-coding
URIs into your code. A snippet from the article I linked-to that defines a URI
template:

<os:URI-Template><http://api.example.org/groups/>{guid}</os:URI-Template>

It's easy to imagine an api client transforming that template into a URI to
retrieve group information without knowing about or caring about the specifics
of the URI format -- it's a black box with the exception of '{guid}.' When
provided with that information, a client can look at that template, substitute
{guid} with an actual guid value, execute the URI, and get the desired
results. This enables, amongst other things, the API to evolve without
breaking the clients. The api clients must know how to interpret the set of
template variable names used by the api ( guid, appid, selector, etc. in the
example provided in the article), but that's it.

I'm sure there's more to it than that, but that's the part that resonated with
me.

