Skip navigation

This is Volume 37 of This week in REST, for June 1 2011 – June 27 2011. For more information on this blog see this post. If I missed an interesting blog post, discussion or paper – just e-mail me the links, tweet or leave a comment on the latest blog post. Thanks!

Around the Web

designing a RESTBucks media-type – “for this blog post, i’ve commandeered the RESTBucks examples from REST in Practice in order to illustrate a simple methodology for expressing application domain details as hypermedia types in a way that works for HTTP and the Web. keep in mind this is my own interpretation of the RESTbucks example and is not meant to indicate the endorsement or approval of the authors of REST in Practice.the material that follows is based on content from a new book i am working on entitled “Building Hypermedia APIs with HTML5 and Node” that will be released later this year.” (by Mike Amundsen)

W3C TAG meeting 6-8 June 2011 in Cambridge, MA, USA – Agenda and minutes from the latest W3C TAG meeting + comments from Jeni Tennison.

HttpRange14Webography – A chronology of discussions about the HTTP range-14 issue.

Media Type Specifications and Registration Procedures – “This document defines procedures for the specification and   registration of media types for use in MIME and other Internet   protocols.” (IETF draft – N. Freed, J. Klensin, T. Hansen)

HAL – Hypertext Application Language: A lean hypermedia type for RESTful APIs – “HAL is a simple, generic hypermedia type based on JSON and XML for use in RESTful APIs. Essentially, HAL provides a set of conventions for expressing hyperlinks to, and embeddedness of, related resources – the rest of a HAL representation is just plain old JSON or XML. HAL consists of two reserved elements: Resource and Link. Any and all elements are legal in a HAL representation provided they do not conflict with HAL’s reserved elements.” (by Mike Kelly) + a comments thread on the REST mailing list

We live in a POST REST/SOAP World – “we now live in a POST REST/SOAP world. Converged (Mobile) Applications have pushed the envelope of what distributed computing should do and how it does it. Never HTTP or SOAP were really prepared for 3-legged authentication, respect privacy and support monetization at the scale of several billion API calls/month. Actually SOAP was a bit more prepared since a message could have a number of security tokens representing different principals, but who cares, we were told that HTTP was the answer, because it was “RESTful” so now we struggle with all kinds of three-legged authentication mechanisms.” (by Jean-Jacques Dubray)

designing a RESTBucks media-type – (by Mike Amundsen)

How Offline Web Apps Should Work – “The essence of this proposal is that a proper solution to the offline web app problem should not require drawing a distinction between “offline” and “online” assets. There is no need for ‘cache manifests’, or to create a separate ‘application cache’ from the standard browser cache.This solution should leverage existing web caching infrastructure (i.e. HTTP headers such as Cache-Control, Etags, etc) to control how browsers store and negotiate the assets required to run the application offline.” (by Mike Kelly)

The trouble with APIs – “1. REST APIs are a case of good intentions run amok. The point of REST was to *eliminate* specific APIs. Not cause their proliferation. 2. When someone says you shouldn’t document a REST API, they’re saying you shouldn’t have an API. Not that you shouldn’t document. 3. That said, RESTians saying you shouldn’t have an API are somewhat vacuous because they offer no good alternative. Custom media types ain’t. 4. Thus, IMO, until we have a workable generic media type or two for the 80% case of “REST APIs”, we’re just growing a frustrating mess.” (by Stuart Charlton)

The Good, the Bad, and the Ugly of REST APIs – “Adrian Cole of jclouds and I have written a lot of code against a variety of SOAP and REST cloud computing APIs. We’ve seen a lot of the good, the bad, and the ugly in API design and we tend to complain to each other about the things we dislike. This article sums up my thinking on the subject (not necessarily Adrian’s, though Adrian reviewed the document and gave me additional ideas).” (by George Reese) + a comment post from William Vambenepe.

Providing and discovering definitions of URIs – “A few widely known methods are in use to help agents provide and discover URI definitions, including RDF fragment identifier resolution and the HTTP 303 redirect. Difficulties in using these methods have led to a search for new methods that are easier to deploy, and perform better, than the established ones. However, some of the proposed methods introduce new problems, such as incompatible changes to the way metadata is written. This report brings together in one place information on current and proposed practices, with analysis of benefits and shortcomings of each.The purpose of this report is not to make recommendations but rather to initiate a discussion that might lead to consensus on the use of current and/or new methods.” (by Jonathan Rees)

What REST needs to do to succeed in the enterprise – “In the spirit of constructive criticism here is what REST needs to do in order to succeed in the enterprise and B2B markets, the sort of markets that make actual revenues and profits as opposed to hype markets with the stability of a bubble. First off there is the mental change required, four steps here. Focus on how people and especially teams work. Accept that HTTP isn’t a functional API. Accept that enterprise integration, B2B and Machine to Machine require a new approach. Accept that the integration technology isn’t the thing that delivers value.” (by Steve Jones)

REST isn’t undead in the enterprise… its still born – “All this just proves what I’ve said for a long time. REST works for information traversal, but its not set up for the enterprise. So what is the issue with REST not displacing SOAP in the enterprise? …. REST needs a standard way to publish its API and for a way to notify changes in that API. This is a “solved” problem in IT but for some reason the REST community appears to prefer blaming others for the lack of enterprise success of their technology rather than facing up to the simple reality…” (by Steve Jones)

All About EVE: Extensibility, Versioning, Evolvabiility, etc. through Modifiability – Excellent presentation slides on versioning and evolvability in (RESTful hypermedia) systems. (by Mike Amundsen)

REST mailing list

Definition of a Hypermedia Client – excellent attempts at defining a hypermedia client.

Stateful APIs – “Consider a simple photo storage service as an API. Users can only interactwith the API if they’ve got an account. Let’s say authorization happensoverHTTP Basic. Given that, would you use URIs like /photos and /photos/{id} (as a photo listand photo detail resource, respectively)? What’s weird about those URIs isthat my /photos is a different list of photos than your /photos — in otherwords, the resource represented depends on the information intheAuthorization header.”


ICWE2011 – The 11th International conference on Web engineering was held at Paphos, Cyprus. Check out the program page for the list of presented papers and the workshops page for the list of workshops. I didn’t go through the papers from all the workshops yet, but at lest 2-3 papers from the main conference should be interesting in the context of REST:

  • Irum Rauf and Ivan Porres. Validating Behavioral RESTful Interfaces using Semantic Web Technologies
  • Kamara Benjamin, Gregor Bochmann, Mustafa Emre Dincturk, Guy-Vincent Jourdan and Iosif Viorel Onut. A Strategy for Efficient Crawling of Rich Internet Applications
  • Ivan Zuzak, Ivan Budiselic and Goran Delac. Formal Modeling of RESTful Systems Using Finite-State Machines (draft of full paper is here, presentation slides are here)

The proceedings of the conference are published by Springer, but I’m sure that Googling for paper titles will also go a long way.

Interesting tweets

@svrc – “REST APIs are a case of good intentions run amok. The point of REST was to *eliminate* specific APIs. Not cause their proliferation.”

@sallamar – “What the discussions about failure/success of REST are missing – (a) that REST is NOT prescriptive and so don’t try to make it prescriptive”

@svrc – “When someone says you shouldn’t document a REST API, they’re saying you shouldn’t have an API. Not that you shouldn’t document.”

@pkeane – “theory: value (+ maybe RESTfulness) of an API can be measured by how easily I can open a representation in a text editor & make sense of it”


  1. When you pull the state of a resource to see if anything changed, you don’t have to tell the provider what kind of change you are interested in. If, on the other hand, you want the provider to notify you, then they need to know what you care about. You may not want to be notified on every single change in the resource state. How do you describe the changes you care about? Is there an agreed-upon set of states for the resource and you are only notified on state transitions? Can you indicate the minimum severity level for an event to be emitted? Who determines the severity of an event? Or do you get to specify what fields in the resource state you want to watch? What about numeric values for which you may not want to be notified of every change but only when a threshold is crossed? Do you get to specify a query and get notified whenever the query result changes? In WS-Notification some of this is handled by WS-Topics which I still like conceptually (I co-edited it) but is too complex for the task at hand.

  2. I’m not sure you can do that in a generic way since resoruces of different media types will have different ways of changing. For example, for a JSON document I could say “notify me every time that the user.address property changes” while for an image resource I could say “notify me when the average color of the image is red(ish)”. There are a lot of media types on the Web, and having a generic way of specifying such changes is pretty much impossible. Perhaps only on a byte-diff level (notify me when more than 30% of the bytes change :)?

    I guess that the options are to focus on a specific media type, or introduce additional metadata concerning resource modification e.g. let the request that is changing the resource contain additional info about the change, and then the client interested in resource changes can subscribe with a query over that info. This could be done with something as simple as a list of keywords.

    Btw. is your name really Tania V. Duffy? I don’t see you on the list of people who edited the WS-Topics spec (which I haven’t read, btw).

  3. Whoa! This blog looks just like my old one! It’s on a totally different topic but it
    has pretty much the same layout and design. Superb choice of colors!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: