brain.dump()

Open Questions About REST APIs, Part II

2013-01-20T00:00:00-08:00

What follows is a fairly wandering article that covers two very important topics: versioning and content types. Please do try to bear through.

Another common discussion in the REST-over-HTTP world is that of long-term maintainability: specifically, how can we introduce versioning so that our existing clients rarely (if ever) break as we make changes. The question of what to version is much more rarely asked, and has led to a quite a bit of conflicting advice and mis-applied best practices.

Versioning Interfaces

Represented simply, REST is describing a system where a client application asks a service for a representation of a named resource. While this is only a small subset of the number of systems involved in actually implementing a RESTful service, these are the places where HTTP interface designers most commonly discuss versioning. Specifically:

Client versioning
Server versioning
URI versioning
Schema versioning

A version is little more than a label we apply in order to give things context. They serve as guideposts, giving us the ability to calculate distances, make promises about compatibility, and to locate faults and shortcomings within our codebase and within time.

Application Versioning

Given that context, we can easily derive value from the versions we give our applications and libraries, especially as software is shipped to the real world. By including that version information in requests and responses, we can gauge adoption of new versions and discover compatibility-related faults. The HTTP spec even encourages the inclusion of these kinds of information, in the User-Agent, Server, and Via headers.

We could also use that version information to selectively serve (or request) different (read: compatible) content. While this has been done for years (with moderate success) as a workaround for poorly behaving web browsers, the approach lacks most of the stability desired of a programatic API.

URI Versioning

Versioning a URI scheme is a tricky proposition. On the one hand, you can spend weeks designing a perfect URI hierarchy for your application's resources, and really nail the execution so that your URIs never have to change again. On the other hand, you're not prescient. You'll miss things. Your user's needs will change. Even in the best case, unless you're developing and abandoning the simplest of tools, ongoing development makes it highly likely that your data model will eventually change, making your carefully crafted URI scheme obsolete.

In the worst of all possible cases, you realize that you need to completely rearchitect your API. Backwards incompatible, no hope for redemption. Oh, you'll still have to keep the old API around for legacy clients, but you need a clean slate…

Like a storybook hero, /api/v2 bursts through the door and proclaims its heroism – and in some ways, it may be right. Cool URIs don't change, and making the version number a part of the URI makes it easy to guarantee that no matter what changes, they'll never have to. Perfectly future-proof.

Except, the version number isn't actually a part of the resource's name, so now you have multiple names (URIs) for the same resource. Not exactly a deal-breaker, but more complex. Also, by embedding a version number in the URI, you've created the place version numbers live – and the temptation to increment that version number for purposes other than URI scheme versioning is fairly significant.

What you actually want is a form of path namespacing, in much the same way you might namespace a class or a function. Putting the version information mid-path is certainly a simple way to handle that, but putting it at the front of the path (say, as a subdomain) has many of the same drawbacks. (As an aside, Facebook did exactly this when it deprecated api.facebook.com in favor of graph.facebook.com.) Thankfully, path namespacing – and URI versioning in general – are largely unnecessary in a RESTful hyperlinked API.

The Internet is REST

Memorizing page addresses or pathing schemes isn't a requirement for using the Internet, and the reason is actually fairly simple: sites have a "well-known" address (e.g. http://wikipedia.com/), and provide access to their content through a few standard mechanisms (contextual links, HTML forms, etc.). That's it. There's no documentation telling you how to get to construct URIs to get what you need, no secret pages, and no special functionality that can't be reached without editing your browser's location bar (with few exceptions).

This works because people who know what they're looking for can find it by following descriptive links towards their content, and people who don't know what they're looking for can discover things by following those same links. This is the reason why REST mandates hypermedia links – it decouples the concepts and relationships in your data model from the URI scheme.

As some have pointed out, REST clients still need to encode something. When you're building a client for a RESTful (hypermedia) interface, however, you aren't required to hardcode URIs (an implementation detail), but the named concepts and relationships (the domain model) into your application. Not only is that simpler to reason about, but it serves to abstract away the underlying service, making the URIs themselves much less important.

Schema Versioning

This leaves us with the most volatile part of the API: the schema. Fortunately, as with hypermedia links, many proposed solutions exist. As a set of goals for a suitable versioning mechanism, I would expect it to be able to:

Allow clients to request specific versions.
Allow clients to specify more than one supported version.
Include version information in the response when appropriate.
Support non-GET requests.
Play nicely with caching.
Play nicely with existing HTTP standards.

Versions in URIs

While we've already dissected the use of versions as URI namespacing mechanisms, some have argued that they may be an appropriate way to version the schema as well.

GET /api/v3/user/joe HTTP/1.0

Pros

Simple, convenient, and direct.
Totally cacheable.

Cons

Conflates the resource name and the version string.
Single version only.

Query strings are another in-URI way of communicating a request for a particular schema version. This avoids the problem of embedding the representation version in the resource name, but unfortunately ties it to the request instead - not to the desired representation.

GET /user/joe?version=3 HTTP/1.0

GET /user/joe?version=3.x HTTP/1.0

GET /user/joe?version=3&version=4 HTTP/1.0

Pros

Simple, convenient, and direct.
Totally cacheable.

Cons

Version is not, strictly speaking, a parameter of the request.
Behaves poorly with non-GET requests.

Verdict

These aren't actually awful solutions – not really – but they do quickly create problems for more complex APIs. Imagine asking yourself, "Does the v2 representation of a user support comments? Which representation versions are supported?"

To look at it from a different perspective, embedding versions in the path is akin to calling "5-year-old Jimmy" a completely different entity from "50-year-old Jimmy". While Jimmy is certainly more mature at age 50, the hope is that he would (at some level) be identifiable as the same individual. Versions in the query string are somewhat like asking to see Jimmy (at 50) is his 5-year-old clothing.

What we really want to see is a photograph of Jimmy at age 5. If that information can't be modeled well in the URI, maybe we can fit it in the headers…

Custom Version Headers

The simplest way to push this kind of information into the headers is simply to do it ad-hoc. If that notion doesn't appeal to you, you could probably also find a proposed standard to latch onto.

GET /users/1 HTTP/1.0
X-API-Version: 3.x || 4.2.0 - 4.5.2

HTTP/1.0 200 OK
X-API-Version: 3.2.4
Content-Type: application/json
Vary: X-API-Version

{}

Pros

Allows a variety of version range syntaxes.
Supports non-GET requests.

Cons

Non-standard (but permitted).
A header like this is still a parameter of the request itself, not of the representation.

Verdict

This is more or less equivalent to the query string example offered earlier, with a couple of drawbacks. It's regrettably difficult to link directly to a specific representation version with headers. As a further complication, caching is easily broken if you omit the appropriate Vary header (which is used to specify on which request headers the current response is based).

Perhaps most frustratingly, while all of the discussed options are functional, none of them actually addresses the core issue: specifying a representation version. There is, however, something built into the HTTP spec for that very purpose.

Content Type Headers

The Accept and Content-Type headers are used by HTTP agents to communicate about the type of data being transferred. Before we dig too deeply into how they might apply to versioning, we should first examine how they're intended to be used in general.

These headers both use standard MIME types to describe the format of the contained content. Other content attributes such as encoding, (spoken) language, and character set are notably not a part of this particular conversation – other headers handle those attributes. As a refresher, the general format of a MIME type is this:

{type}/{subtype} (; {parameter.name}={parameter.value})*

type is defined to be one of eight primary groups, text, image, audio, video, application, model, message, or multipart. The first four are exactly what they sound like, with application serving as both executable code and as a kind of binary "catch-all", model providing a way to describe a 3D mesh, message representing a mail message, and multipart being a way to include multiple pieces of data in the same communication.

subtype is a registered data format name, usually corresponding to the well-known name of the format. image/png, text/plain, and application/javascript should all feel pretty familiar. There also exist provisions in the RFCs for proprietary, personal, and experimental subtypes, though these are likely "policed" somewhat less rigorously.

parameters are, unsurprisingly, key-value pairs that provide additional context for the format. As an example, some audio subtypes may define a 'bitrate' parameter, denoting the audio quality. These parameters are a part of the subtype's (or occasionally the type's) registered description, have very specific meanings, and may be declared as either required or optional. To quote from the RFC:

New parameters SHOULD NOT be defined as a way to introduce new functionality in types registered in the standards tree, although new parameters MAY be added to convey additional information that does not otherwise change existing functionality. An example of this would be a "revision" parameter to indicate a revision level of an external specification such as JPEG. Similar behavior is encouraged for media types registered in the vendor or personal trees but is not required.

Content Type Negotiation

One of the goals behind HTTP was to reduce the amount of round-trip communication required to fetch a resource. To that end, a negotiation protocol was built-in. The rules break down thusly:

The Accept header of the request should contain an unordered, non-empty set of comma-separated MIME media types, including parameters.
Each MIME media type in the Accept header may have a special parameter q, with a value between 0 and 1 indicating the agent's relative preference for that media type. In the absence of the parameter, a value of 1.0 is assumed.
Both the MIME type's type and subtype subtype fields may (independently) have a special value of '*', which acts as a wildcard.
Precedence of types with identical q values should be ordered by specificity. The term itself seems loosely specified, but a general algorithm might be:

  (non-wildcard type) + (2 * (non-wildcard subtype)) + (3 * parameter count)

In the absence of clear precedence, the server is free to choose based on its own preferences.
In the absence of an Accept header, the server should assume a type of */*.

(Similar rules apply to all the Accept-* and Content-* headers.)

With this setup, an agent can make a single request of the server for any data format it can handle, specify its own preferences, and (usually) expect to get back meaningful data. Applying these principles to a REST-over-HTTP interface seems valuable, but finding an appropriate granularity may be difficult.

Meaningful Content Types

As an example, let's pick on application/json for a minute. JSON is a great transport format, balancing simplicity of parsing with human readability. But, if our application is generating JSON (as opposed to simply serving JSON files from an unknown source or sources), is the general type application/json really the most appropriate descriptor? Well … maybe not.

Atom and RSS are just particular XML schemata, but a feed reader wouldn't want to accept arbitrary XML. Instead, it Accepts the more specific application/atom+xml and knows not only how to parse the data, but what the data means. Great plan.

Off you run to mint your own MIME type, say application/x.myapp+json, but something doesn't quite feel right. Your content is in many ways just a subclass of JSON, but naïve JSON parsers won't recognize that. There's a long discussion of why the +basetype syntax is "good enough" available in the RFC.

Is your MIME type granular enough, though? You've got a type for your application now, but you presumably return several distinct resource types from your API, each with a different schema. Now you have an inheritance problem again. application/x.myapp.user+json isn't bad, but you'll need a separate MIME type for each resource schema you expose, and there's no programatic relationship between those types and any internal conventions or external standards they conform to.

I would be uncomfortable if the content negotiation process implicitly "upcast" the results of a request (e.g. Accept: application/json -> Content-Type: application/x.myapp.user+json). On the one hand, it's not the kind of response I asked for ("do you support content negotiation properly?"), and on the other, while it is valid JSON, I can't easily verify that by looking at the Content-Type. "Downcasts" cause many of the same problems.

If you want real inheritance-like behavior for your application, you're usually stuck implementing it by hand. Your resource's proper MIME type is application/x.myapp.user+json, but you can write a server that will automatically cast the result to any number of other implemented interfaces: application/x.myapp+json, application/json, application/hal+json (if supported)… It's far from ideal, but this is the only practical option I'm aware of today.

Versions and Content Types

Now we actually have to answer the question of how that custom MIME type gets versioned, and we should also consider how that version plays with content negotiation.

At a glance, there are a few distinct ways to include the version:

application/x.myapp.resource.v2+json
application/x.myapp.resource-v2+json
application/x.myapp.resource+json; version=2

The first option available feels strongly as if the version is an integral component of the representation; neither a good nor a bad thing, but it doesn't ring true with how I tend to conceive of versioning. The first version of X is fundamentally related to the second version of X, by more than just a lexicographically similar name.

The second option tries to make a distinction between the type name and the version component by introducing another sub-name component. Whether the concept of a "version" should be a parameter of a type seems to be the primary division between options #2 and #3, so let's dig into the RFC again.

Parameters are modifiers of the content-subtype, and do not fundamentally affect the requirements of the host system.

Frankly … I don't know what the "host system" is. Actually, I'm fully at a loss. My sense of aesthetics prefers the separation offered by option #3, but I can't justify it well, and I won't begin to claim to know the ideological fallacies (or the real-world risks) I'd be committing to by using it for those purposes. Then again, I'm finding it difficult to find heavily parameterized media types.

As much as I'd like to say, "just look at what GitHub does", I'm not particularly convinced by their approach either – most specifically, they use a single vendor subtype (vnd.github) and specify version and "param" as dot-separated components of the subtype (vnd.github.v3.raw+json). Notably absent is any recognition of the represented resource schema: the "param" value is only advice to the underlying responder e.g. about how to process Markdown content. The responses they send actively "downcast" the content type to the underlying format (e.g. application/json), and the "actual" media type is returned in a custom header.

HTTP/1.1 200 OK
X-GitHub-Media-Type: github.v3; param=full; format=json

Content-Type versioning as a construct, however, seems useful, and in line with the concerns of schema versioning.

GET /users/1 HTTP/1.0
Accept: application/x.myapp.user+json; version=2; markdown=raw; compact=yes,
        application/x.myapp+json; version=2; markdown=raw; q=0.8,
        application/json; q=0.1

HTTP/1.0 200 OK
Content-Type: application/x.myapp.user+json; version=2; markdown=raw; compact=yes
Link: </users/1>; rel="self"; type="application/x.myapp.user+json; version=2; markdown=raw"
Link: </users/1/profile>; rel="related"; type="application/x.myapp.profile+json"
Vary: Accept

{}

Pros

Content-Type negotiation is a well-established standard for handling data type resolution.
Supports non-GET requests.
Can be cached.

Cons

Version information lives in the content type, so additional data is required for Links.
Finding the proper abstraction level in your MIME types can be difficult.
MIME type inheritance is effectively non-existent.

Verdict

This feels like less of a "home run" than it should. I appreciate the clear conceptual separation of the type parameters, but I'm not feeling great about the custom MIME subtypes. Doing content negotiation for well-known formats is awesome; doing content negotiation for unknown (or poorly known) formats is distinctly less so. Communicating type information with each link is particularly uncool – though that's less an artifact of the versioning scheme, and more about having so many distinct schemas throughout the application.

Versioning Well-Known Media Types

Let's try a little mental exercise, and work backwards from our last conclusion.

Why did we end up with a content type of application/x.myapp.user+json; version=2? We got there by adding the version to the content type, as a parameter. This gave us the ability to negotiate versions using the standard content type negotiation, and fell neatly into a pattern whereby we could make other "sub-schema" level alterations to our type.

Before that, we had a content type of application/x.myapp.user+json. We used that content type to represent the schema of the returned data. Our subtype name was built up from our namespace (x.myapp), the schema name (user), and the general format of the data (json). We would expect the schema to change between almost every endpoint, but the format would likely remain constant for a given client.

Before that, we had a content type of application/x.myapp+json. This was to "strongly type" the data as belonging to our application (as opposed to being generic content). This also gave us permission to freely declare and use type parameters, as we were the owners of the type description.

Before that, we were using application/json, because that's the well-known MIME type for JSON content.

We've already explored the possibilities around where else the version number might live, and I still believe that the content type seems an appropriate place for it. Let's accept that as given for the moment, and see if there are other assumptions we can challenge.

Communicating about the schema itself seems important, but what if that information didn't live in the Content Type header?

The first question I'd want to ask is, "how does that affect type negotiations?" – and it seems to me that we would stop using different types for each endpoint, which would promote the development of an abstract REST agent, in addition to making clients easier to write as they have one fewer dimensions in type names.

The second question is, "where does the schema information live?" That may be a trickier question, but there is a draft proposal for a "profile" link relation intended for this very purpose. In fact, one of the targets of that proposal is to be able to describe multiple profiles the content deliberately adheres to. Let's accept with the "profile" relation for now.

The schema concerns addressed, let's look back at our media type (application/x.myapp+json). The benefit this type gives us is twofold: it communicates about the content producer, and it gives us a place to use type parameters. As discussed earlier however, we've already got a much clearer place to list the content's producer in the Server header. We do (officially) lose a place to attach type parameters; we'll ignore that for the moment.

When finally assembled, the solution we have looks like this:

GET /users/1 HTTP/1.0
Accept: application/json; version=2; markdown=raw; compact=yes,
        application/json; version=1; markdown=raw; compact=yes,
        application/xml; version=2; markdown=raw; q=0.5

HTTP/1.0 200 OK
Content-Type: application/json; version=2; markdown=raw; compact=yes
Link: </schema/user>; rel="profile"; name="user"
Link: <http://stateless.co/hal_specification.html>; rel="profile"; name="HAL"
Link: </users/1>; rel="self"
Vary: Accept

{}

Pros

Content-Type negotiation is a well-established standard for handling data type resolution.
Content-Type negotiation is done around well-known types.
Profile links allow something akin to inheritance.
Supports non-GET requests.
Can be cached.

Cons

Version information doesn't live in the URL, so additional effort is required.
Violates the specifications of well-known media types.

Verdict

From the perspective of the HTTP clients I've written, this seems fairly sane. The content type is very likely to remain stable for the entirety of my client's life, and what changes are made are flags that can be independently tuned. Violating specs seems to be a growing theme here, but I'm not overly concerned about it at the moment.

All told, I feel reasonably comfortable with this solution (despite its drawbacks). I may also simply be unable to see the forest for the trees at this point – please leave your thoughts and preferences in the comments.

Open Questions About REST APIs, Part I

2013-01-01T00:00:00-08:00

Designing an HTTP-based API is a fairly straightforward task, all things told. A proper REST API is a much smaller target, and while some of that comes down to the constraints REST advocates for, a larger portion deals with the long-term maintenance and evolution of that API.

The REST Constraints

REST is less about a protocol than it is about interface design, and the design is constrained by a few principles:

Clients and Servers communicate about identifiable resources. These communications take place using representations of resources (XML, JSON, PNG, etc.), and each resource has a globally unique identifier.
Each message is self-descriptive. Content-Type is an oft used example here; each message must clearly denote what types of content it contains, so the recipient may handle it appropriately.
Each Client response contains enough information to manipulate the resource. If permitted to do so, the Client should have enough information to delete or update a resource on the Server. That information may be in the resource representation itself (e.g. the resource ID, a version identifier), or elsewhere in the message.
Client interactions are driven by hypermedia. With few exceptions, Clients are expected to "navigate" the API dynamically, rather than hard-code service URL patterns. The most common example for this is the web as it exists today: you tend to follow links rather than guess at URLs, and your browser provides a handy mechanism for that.

REST-over-HTTP gives us a nice common ground for discussion. The model is Client/Server, we're not actually passing the only copy of resources around, messages are reasonably self-descriptive (thanks in part to HTTP headers), and … wait, where are the links?

Links

This is the biggest difference between most "RESTful" APIs today and the core definition of REST. In the absence of hypermedia links, you are left with a resource-oriented Client/Server API with a limited set of available actions (the HTTP verbs). While that's certainly a valid API design, it requires Clients to hardcode an understanding of the Server's URI patterns and data model, which ultimately leads to the brittleness and change-resistance that REST seems best suited to avoid.

This isn't terribly surprising, either. Many of us learned what "REST" is by restructuring our URIs into a resource hierarchy – and for some of us, that was itself a significant cognitive challenge. Even today, the Rails documentation sometimes conflates resource-oriented with REST, and many books still omit hypermedia links from their definition of REST.

Part of the reason for this is a lack of best practices. HTML has long used the anchor tag (<a>) as a way of navigating collections of documents, and has expressed other relationships in other ways (e.g. <link>, <img>, <script>) – you would be hard pressed to find an HTML document that didn't leverage links. XML can easily adopt some of these conventions, but JSON (and many other representation formats) have a harder time of it.

In an effort to derive a general solution, it may be useful to start with some guiding parameters. A desirable solution:

Allows Clients to "follow their nose" through your application, starting from a small number of known entry points.
Permit Clients to avoid having to "guess" at URIs.
Should be lightweight (in terms of both network and cognitive overhead).
Can express links to alternate representations of the same resource, related single resources, and members of a collection.

On the other hand, a desirable solution need not:

Specify which actions are permitted for a link.
Encode the links as a part of the resource representation.

JSON-LD

A JSON convention, JSON-LD has been described as a direct port of RDF to JSON. In its simplest forms, you end up creating two parallel object graphs – one of your data, the other of links to other data. Tooling exists to transform these disjoint graphs into a single, unified graph, in addition to many other graph transformations.

{
  "@context": {
    "name": "http://xmlns.com/foaf/0.1/name",
    "homepage": {
      "@id": "http://xmlns.com/foaf/0.1/homepage",
      "@type": "@id"
    }
  },
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
}

Pros

Reasonably small footprint (few reserved property names).
Links are provided in the data.
Enables metadata for every field without altering data model.
Allows external linkage to metadata descriptions, for readability.
Easily extended beyond relationship metadata.
Fairly well supported.

Cons

This is only a solution for JSON.
Complex metadata quickly overwhelms the original data.
Seems primarily focused on describing types, not relationships.
No fields can be assumed to be links.
Semantics are not immediately clear.

Verdict

A remarkably complete standard, but it feels distinctly cumbersome to achieve the basic goals of hypermedia links. This is probably a good candidate for something – just not this.

HAL

Targeted squarely at JSON and XML, HAL aims to standardize the discovery of resource links, by storing them all in reserved properties.

{
  "_links": {
    "self":   { "href": "/orders" },
    "next":   { "href": "/orders?page=2" },
    "find":   { "href": "/orders{/id}", "templated": true },
    "search": { "href": "/orders{?keyword}", "templated": true }
  },
  "_embedded": {
    "orders": [
      {
        "_links": {
          "self": { "href": "/orders/123" }
        },
        "currency": "USD",
        "status": "shipped",
        "total": 30.1
      }
    ]
  },
  "currentlyProcessing": 14,
  "shippedToday": 20
}

Pros

Reasonably small footprint (only two reserved property names).
Links are provided in the data.
Open set of link relationships.
Fairly well supported.

Cons

This is only a solution for XML and JSON.
Obscures the interesting data somewhat.
Forces nested JSON resources into the _embedded key (somewhat unnatural).
Requires a custom MIME type.

Verdict

The _links key does a nice job of providing an accessible table of contents for links pertaining to the requested resource. The _embedded key however, which aims to aid discovery of nested resources, breaks common conventional uses of JSON. This might be a viable solution, though it doesn't generalize beyond JSON.

Link Headers

The other main solution on the table leverages that big blob of metadata we already send with every message: HTTP Headers. In fact, there's already an accepted standard for including linking information in response headers.

HTTP/1.1 200 OK
Content-Type: application/json
Connection: close
Link: </orders>; rel="self"
Link: </orders?page=2>; rel="next"

{
  "stuff": 0,
  "moar-stuff": 1
}

Pros

Zero data changes.
Works for all content types.

Cons

Links are not provided in the data.
Restricted set of link relationships – extensions are possible, but a bit kludgy.
Doesn't naturally describe links for nested resources.
Less easily "discovered" by casual API consumers.

Verdict

This actually proves to be a fairly neat solution for REST-over-HTTP, regardless of the representation. Where in an HTML document many of the links are contextual, they are typically less contextual in API data – given that, keeping them in the message's metadata may make a lot of sense.

Not including the links in the representation data itself is a problem in a few distinct circumstances, notably when the response headers aren't available to consumers (e.g. JSON-P requests). This problem is further exacerbated by the fact that other important metadata may also be included in those headers, such as status codes and API request limits.

GitHub has implemented a solution for their own API, where JSON requests containing a callback parameter are served a response (with a different MIME type) that invokes the named callback function, passing it a hash with two keys, meta and data. The data key is identical to the standard JSON response, and the meta key is a JSON serialization of the relevant header information.

callbackFunction({ "meta": { /* HEADERS */ }, "data": { /* JSON */ } });

In the case of JSON-P, the header metadata could probably be passed as a second parameter to the callback – that would allow the received data to be identical to the "standard" (i.e. JSON, no callback) response, while making the metadata accessible to interested clients. (I'd love opinions on whether this is better or worse overall.)

// If the callback only accepts a single parameter, Javascript will silently
// ignore the headers object. If the callback function accepts two parameters,
// but the headers aren't passed, Javascript will pass `undefined` instead.
callbackFunction({ /* JSON */ }, { /* HEADERS */ });

Other client environments may have similar difficulties retrieving the response headers. Given that I'm less familiar with those environments, and that we've produced two distinct viable workarounds for this case, I'm reasonably confident that the concern can be ameliorated.

The other major concern with this approach would be how related resources could be linked to. Self-linking is easy, as are links to other collections of similarly represented data.

HTTP/1.1 200 OK
Content-Type: application/json
Connection: close
Link: </users?offset=0>;  rel="first"
Link: </users?offset=0>;  rel="prev"
Link: </users?offset=10>; rel="self"
Link: </users?offset=20>; rel="next"

Any-to-One Relationships are also reasonably easy to specify, but getting meaningful semantics into place can prove a little trickier.

HTTP/1.1 200 OK
Content-Type: application/json
Connection: close
Comment: "Fully standards compliant, but useless."
Link: </users/1>; rel="related"
Comment: Using custom relationships, we get a bit closer.
Link: </users/1>; rel="http://example.net/relation/owner"
Comment: Using custom Link parameters; permitted, not well documented.
Link: </users/1>; rel="related"; name="owner"

Any-to-Many Relationships face similar difficulties, but with an added complication: a mapping needs to be created between the Link header and the representation.

HTTP/1.1 200 OK
Content-Type: application/json
Connection: close
Link: </users/1>; rel="item"; name="user"; index="0"
Link: </users/5>; rel="item"; name="user"; index="1"
Link: </users/8>; rel="item"; name="user"; index="2"
Comment: ...
Link: </users/20>; rel="item"; name="user"; index="99"

{
  "books": [
    { "id": 1, "title": "Foundation" },
    { "id": 5, "title": "Foundation and Empire" },
    { "id": 8, "title": "Second Foundation" },
    "...",
    { "id": 20, "title": "Final Destination" }
  ]
}

Aside from being an undesirably complex solution, this also has the potential to cause trouble with web servers and proxies that put heavy restrictions on header count and length. In addition, there's a quite a bit of duplication involved here, which can be costly.

URI Templates give us a way to address some of that duplication, if we're willing to accept cooperation between the data model and the metadata.

HTTP/1.1 200 OK
Content-Type: application/json
Connection: close
Comment: The Link header specification says that the value in the angle brackets
Comment: must be a valid URI Reference, meaning that we can't simply do this:
Comment:   Link: </users/{id}>; rel="item"; name="book"; collection="books"
Comment: Instead, we can get away with this:
Link: <>; rel="item"; name="book"; collection="books"; template="/users/{id}"

{
  "books": [
    { "id": 1, "title": "Foundation" },
    { "id": 5, "title": "Foundation and Empire" },
    { "id": 8, "title": "Second Foundation" },
    "...",
    { "id": 20, "title": "Final Destination" }
  ]
}

The headers provide enough information to construct valid URIs for each collection member, without the overhead of repeating the information for each item (in either the headers or the data).

Final Thoughts

For my own purposes, I could abide using HAL, but the Link headers approach feels much more generally appropriate. The existence of formally defined item and collection relation types indicates that some thought has been applied in this area, but I've found very little information about putting it into active practice. I may build a prototype API using the Link headers if the idea doesn't seem completely broken.

I would appreciate feedback on any part of this, particularly with an eye towards building a generally useful recommendation for adding hypermedia links to today's (and tomorrow's) REST interfaces.