REST Tips Prefer following links over URI construction

When putting together a table to describe your REST service, and believe me, I've been seeing a lot of these tables recently, there needs to be a distinction between the server view and the client view.

For example, here is our table for the employee service from my worked example of how to create a RESTful protocol:

The important point is that this is the server's view of the service, the table is a guide to the implementor of the service on how to structure the URIs. The view that actually gets documented and presented to the client needs to be slightly different, the most important part being the replacement of URI construction with links.

As a reminder, here is an example of the employee list, which contains the URIs of the employee resources.

  [
    {
      "name": "Joe Gregorio",
      "href": "jcg111002222"
    },
    {
      "name": "John Q. Public",
      "href": "jqp333445555"
    },
    ...
  ]

Figure 1
Employee List JSON Representation

Here is our table as it should be presented to client implementors:

Note that the client doesn't get to 'know' how to construct employee URIs from employee-ids, instead it just follows links from the employee list to each employee resource.

Tip: Prefer following links over URI construction.

There are still cases for URI construction, where the representation given is really a recipe for how to construct a URI, such as an HTML form, or an OpenSearch document. Even in these cases, the client doesn't have hard-coded knowledge on how to construct a URI, it is only following the recipe in the HTML form, or OpenSearch document. If the recipe gets updated the client will follow the new recipe without needing to be modified.

There are several advantages to keeping URI construction out of view of the client:

Simpler Client Code

The client code is simpler, dereferencing a (possibly relative) URI is simpler than constructing a URI and then dereferencing it.

Server flexibility

The URIs on the server side can be changed as needed without having to update all the clients. Yes, you should strive for unchanging Cool URIs, but mistakes happen and this lets you fix those mistakes without updating the clients.

This isn't just idle theory, at one point in the development of the Atom Publishing Protocol there was a push for a form of URI construction, a WebDAV like use of the URI path for creating and manipulating resources. Luckily that never made it into the specification, because now I can create a service document for a group of APP collections that currently don't have service documents:

The resource at http://bitworking.org/projects/gdata/gdata-service.atomserv is a service document for all my APP collections on Google, and it looks like:

<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://purl.org/atom/app#"  xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace> 
    <atom:title>Google</atom:title>
    <collection href="http://www.google.com/calendar/feeds/default/private/full">
        <atom:title>Calendar</atom:title>
    </collection>
    <collection href="http://base.google.com/base/feeds/items" >
        <atom:title>Base</atom:title>
    </collection>
    <collection href="http://www.blogger.com/feeds/6464869902972579239/posts/default" >
        <atom:title>Blogger (jcgregorio)</atom:title>
    </collection>
    <collection href="http://spreadsheets.google.com/feeds/spreadsheets/private/full" >
        <atom:title>Spreadsheet</atom:title>
    </collection>
  </workspace>
</service>

http://example.com/employees/jcg111002222

>>> import urlparse
>>> urlparse.urljoin("http://example.com/employees/", "jcg11102222")
'http://example.com/employees/jcg11102222'
>>>

/employees/?name=Joe