It is not often that a full one second improvement to the response time of an HTTP request so insignificant that it is not worth committing.

I have leaned in both directions at various times. I have never fully convinced myself either.

To make the issues a bit clearer let me use and example lifted from the article that got me thinking about this most recently.¹

<cart>
  <!-- some stuff here -->
  <link rel="http://ex.org/rel/abort" 
        href="http://ex.org/cart/cancel;token=987654321"/>
  <link rel="http://ex.org/rel/add-more" 
        href="http://ex.org/cart/add;token=987654321"/>
  <link rel="http://ex.org/rel/buy" 
        href="http://ex.org/cart/buy;token=987654321"/>
</cart>

I place this example in the “links for every action” camp. Each of the links in the example describes exactly one action.

An alternate approach might look something like this.

<cart>
  <!-- some stuff here -->
  <link rel="http://ex.org/rel/line-items" 
        href="http://ex.org/cart/line-items;token=987654321"/>
  <link rel="http://ex.org/rel/new-order" 
        href="http://ex.org/orders?cart=987654321"/>
</cart>

From a client perceptive these are a bit different.

Abandoning cart

A client that wants to abandon a cart in the first example would make a DELETE or POST – it’s a bit hard to tell which from the example – request to the href of the http://ex.org/rel/abort link. In the second example a similar client would just DELETE the cart resource.

Adding item

When adding an item in the first example the client would post a www-form-urlencoded document containing the URI of the item to add and the quantity to the href of the http://ex.org/rel/add-more link. In the second example, the same document gets posted to href of the http://ex.org/rel/line-items link.

Placing order

In the first example the client would make a POST request to the href of the http://ex.org/rel/buy link. In the second example the client would POST a www-form-urlencoded document containing the cart URI and some payment information to the href of the http://ex.org/rel/order link.

Differences

Obviously the to approaches result in quite similar markup. The same behavior is encoded in both. In the first example the links are action oriented. All actions that can be taken on an item are explicitly stated using a link. In the second approach the links are data oriented rather than action oriented. Rather than having separate links to retrieve the current line items and to add a new line item the http://ex.org/rel/items link provide both actions using the GET and POST HTTP methods respectively.

The first approach it better at expressing what actions are allowable at any given point in time. For example, once the purchase process has been initiated it does not make sense to abort a cart. So if you GET a cart after POSTing to the http://ex.org/rel/buy link the representation would not have the http://ex.org/rel/abort link.

The second is more concise because it, at least potentially, provides access to more than one action per link based on the standard HTTP methods. You don’t need to provide a separate abort link because DELETEing the cart is sufficient. You don’t need to provide separate get line items and add line item links because a single link that can handle GET and POST requests will work.

The first approach is a bit more flexible with regard to implementation details. If you need for some reason to have different URIs for the retrieve line item request than the add line item request you could easily achieve it. The second example makes that impossible.

Conclusion

I am still not entirely convinced but i am leaning toward the more flexible, verbose and explicit approach of a link for every actions.² Having links represent actions rather than resources feels a bit odd, but i think it provides more of the benefits we hope to get from a RESTful architecture.

Even if you don’t live in Texas this matters to you because, as the article explains, Texas has a disproportionate influence on text books in the US.

H/T Martin over at The Atheist Experience

I really dislike this idea. It sets my teeth on edge because it treats links – which are possibly the most important bits of data in existence – as second class citizens. It is easiest to show what i mean with a bit of extrapolation:

<complexElement rel="entry">
  <string rel="id">234132</string>
  <string rel="displayName">Peter Williams</string>
  <complexElement rel="name">
    <string rel="familyName">Williams</string>
    <string rel="givenName">Peter</string>
  </complexElement>
  <complexElement rel="emails">
    <link rel="email" href="mailto:pezra@barleyenough.org"/>
    <string rel="type">personal</string>
  </complexElement>
</complexElement>

That is what a portable contact might look like if we treated all data the way link elements work. That example looks pretty ugly to me, as i suspect it does to most people. It is ugly because very important information regarding the role of elements is relegated to a subsidiarity position in favor of fairly unimportant information about its type. However, link elements do to links exactly what my example does to all the data. The effect is that properties whose values happen to be independently addressable resources are obfuscated.

The revealed preference of the world is against link elements. Just look at pretty much any format that embeds application specific semantics. As far as i know, there is not a single widely used format that actually represents its links as link elements. Even atom uses properly named elements for most its links. The link element it defines is largely relegated to the back water of extensibility.

One benefit that link elements have, or at least could have if they where more widely used, is the facilitation of standard link processing tools. Fortunately, we do not have to give up the expressiveness and clarity of intention revealing names to achieve this result. Rather than obscuring the links we could just treat them as normal data. The additional information needed to support standard tools could be added in a relatively unobtrusive way. Consider the following:

<entry xmlns:link="http://unobtrusive-generic-linking.org/">
  ...
  <emails>
    <value link:hrefDisposition="elementContent" 
           link:rel="foo">
      mailto:pezra@barelyenough.org</value>
    <type>personal</type>
  <emails>
</entry>

This is idea is similar to xLink but more flexible and simpler to use.

You could expand the idea to JSON with relative ease. Consider the following expansion of the portable contacts json format tagged with some unobtrusive link info.

{"entry": [
  {"id": "42",
  "emails":
    [{"address"   : "mailto:pezra@barelyenough.org",
      "type"      : "personal",
      "_linkInfo" : {"hrefDisposition" : "address", 
                     "rel" : "foo"}}]}]}

Unobtrusive link info makes links visible to and usable by generic link processing tools while protecting the use of intention revealing names that format designers, and users, want. This is important because it allows new formats to reuse “standard” link semantics more easily and uniformly.

Eating and watching television at the same time is seldom done at my house. It must be fun, though, because Audrey lets her stuffed animals do it.

The idea of an application as a set of states (read: representations) with transitions (read: links) to other states seems to go against the idea of storing links. Transitions from one application state to another are surely transient. Any change in the application state, either by this client or some completely unrelated client, could easily invalidate those transitions. In that context a client that stored links for later use would surely be doomed dereferencing dead links for the rest of it’s days.

Further, the idea that clients might store links is a frightening specter for maintainers of services. If clients store links, and you prefer not to break those clients, you must continue supporting any links you have ever included in any representation in perpetuity. Talk about limiting your design freedom. Such a strict requirement would surely raise the cost of maintaining the service over time.

Reality sets in

Those are scary thoughts. Some of these issues are even real. But end the end it doesn’t matter. Almost all non-trivial systems are going to require that URIs be stored in places other than the origin server. Sometimes these stored URIs will merely be caches. Other times they will be data that cannot be recalculated mechanically.

For example, say you have an order taking system and an inventory system. When placing an order the user goes to the web site, searches for “coffee”, selects the third item in the results and places an order 1 of that item. An order is a set of line items each of which references a product. Once payment is received the order system is going to need to be able to tell the shipping department which items from inventory to send to the customer.

The inventory system has, of course, a URI for every type of product that is for sale. So the simplest and most effective way for an order to reference a product is to use that the inventory URI for that product. URIs are called universal resource identifiers for a reason, we might as well use them as such.

In this example, we have a situation where the product references in the order are not merely caches of URIs. Many things may change the ordering of search results – a new product being added, an old one being discontinued, even a small change to a description of some product. So at any moment the the third item in the search results for “coffee” might be different. Once the user has made their selection no automata can reliably retrace those steps.

The implications of this are significant. The inventory must continue to support the product URIs used in orders until such time as the order system would never care to dereference those URIs again. If a month from now the user comes back and wants to see their order history, those product URIs had better still work.

Fortunately, HTTP provides us with a ready solution. Behold the awesomeness that is HTTP redirection. HTTP redirection is your best friend when it comes to gracefully changing REST/HTTP applications. Clients get what they need – URIs continue to work as identifiers indefinitely – and servers get what they need – a lot of freedom to change the names and dispositions of resources.

Transient links

We are still faced with this issue of the transient nature of links. Certainly, many links encode transitions which may be transient. The client has no general way of distinguishing between links which represent transiently available state transitions, and those that represent more permanent transitions.

In our example, immediately after creating an order, it probably provides some links to pay for the order. After the user has provided payment those transition would no longer be valid. However, the link to the inventory product is a more permanent part of the order resource.

The only tractable way i see to deal with this issue is to document the lifespan the various link found in a representation. Once the client implementer understand the semantics of the links they well often be able to infer the likely lifespan of the links without further input. However, guidance can be provided in situations where precision is required or the lifespan is ambiguous. A transient link is, by definition, an option part of the representation so documenting the conditions that cause it to be present is likely to be required anyway.

Best practices: Server

REST/HTTP application developers should assume that clients will store links and dereference them after indeterminate periods of time. When resources are relocated or renamed requests to the resource’s obsolete URI should be redirected to the canonical URI using a 301 Moved Permanently response.

For links whose validity has a bounded lifespan the documentation of the representations (the media type) should explicitly layout that the link is transient and optional. If possible the documentation should also describe the conditions of the links existence.

Remind client developers early and often that client must follow any and all redirects from the server.

Best practices: Client

Clients should follow redirects. Fastidiously.

Clients should update it’s internal storage upon receiving a 301 Moved Permanently response by replace the URI it requested with newly provided location.

Client developers should be aware of transient links in the representations being dealt with. Either do not store these URIs or ensure that attempts so use these URIs handle failure in ways that make sense for the application.

Believe and follow the redirections the server sends to you. Seriously.

It has been a big year. Probably the biggest thing is kindergarten which he loves. He is getting to be a big kid but he definitely still has his little kid moments.

This idea is at the very core of the architecture of the web. However, achieving such compartmentalization has been difficult for business application development. The recent advancement of REST into the mainstream is bringing this mentality within the reach of many development teams.

The small pieces approach totally dominates the lower levels of software development in the form of object oriented programing. Each “object” is a small self-contained piece, and a large number of the small pieces are joined together to provide the functionality of the application.

At the application level, however, this approach does not enjoy the same ubiquity. It is much more common to see a monolithic approach. There is one giant application that does everything for everyone. The path of least resistance for any single new feature is to implement it in the existing application structure. There is some overhead in creating a new application, so in the short term multiple small applications seems more costly.

Unfortunately, while it is easier to add any particular feature to an existing application doing so means you give up all the advantages of small pieces loosely joined. And, the advantages of a small application approach are significant.

Perhaps the single largest advantage is that smaller applications are easier to understand. To effectively improve or maintain software it is necessary to understand it. The connascence of one bit of code and everything else is often unclear. This lack of clarity means that the risk of any particular change having unintentional impacts increases with the size of the code base. Building more smaller applications is an effective way to manage such risks.

Another advantage of this approach is that it makes using novel implementation techniques more workable. If you have a large monolithic application and you get a new requirement that might benefit from a different language, framework or runtime you are pretty much out of luck. In a compartmentalized architecture each application can have it’s own technology stack. If you new a set of features that that might benefit from the concurrency of Erlang you can use for that component without impacting the other components in any way.

Have several small applications often turns intractably large efforts in to several smaller tasks. For example, consider upgrading the framework on which your application(s) are built to a new version. The new version has features and improvements that would be highly beneficial but target version is incompatible with the version you are currently running in some minor ways.

Such an upgrade will necessarily touch most of the application. Its risk profile will be very broad. The benefits of the upgrade will rarely be directly visible to the business so the priority of such work is always rather low. The cost and risk of such work is often so large, and the perceived benefit so small, that such work is put off until support is being terminated for the version currently in use.

In a compartmentalized system the any single component can be upgraded much more quickly, and at lower risk. The benefits of upgrading match the effort required much more closely in such situation. Many times the effort required is often so low there is no discussion required, upgrades become normal refactoring tasks.

Experimentation is also quite a bit more manageable in a compartmentalized architecture. The smaller size of the components makes implementing new ideas faster and more approachable. This lowers the cost of implementing new ideas and recovering if the idea does not pan out.

When experimenting it is often not immediately clear if a new idea really is an improvement. Sometimes developers and users need to work with it a for a while to form a reasoned opinion. In compartmentalized systems experiments can be designed to impact a small portion of the total application. This allows small experiments to can soak for a while until the team is ready to call the results. If idea worked the practice can be expanded to the rest of the components, if not it is only a small portion of the code base that needs to be cleaned up.

It is worth noting that this approach will effectively true your large application into a distributed system of small applications. This is distributed applications are a little scary, and for good reason. Before you embark on this path you should have a plan for how to integrate the parts into a whole. For most business application REST/HTTP is a very good technology for integrating applications.

There are many other situations where the small pieces approach’s conversion of large tasks into small ones is an advantage. There are also situations where it causes more overall work. In my experience, though, the chunking of tasks is well worth the small additional overhead. It is much easier to manage many small semi-independent development efforts than a few large ones.

The parents of kindergartners, on the other hand, are already having a bit of trouble communicating effectively. I fear for what this might mean over the course of the year. As a parent you, of course, want do what you can to enhance the education of the children. You have to do it with a group of people who you have never even meet before the first day of school. Worse yet those people are only loosely committed to the project. Personal issues, personality conflicts or simple disinterest in the task at hand can easily remove many individuals from the effective team at any moment.

It will be interesting to see how the parents self organize over the year. Fortunately, the parents are just support for the teacher. Even if we fail to form a cohesive team i think the teacher will still manage to educate the kids. That is what professionals do.

Speaking of the profession of teaching, the politics teachers have to manage is rather impressive. Even for a class of 25 kindergartners it must be daunting… you have to maintain the interest and respect of 25 kids; keep about 50 parents placated and helping as much as possible; all while keep the principle happy. And to make that more complicated really none of those people get to choose if they really want work with any of the others. And all that before you even get to the job at hand.