I spent last week at 9300ft above the sea level at Keystone (CO) attending the Colorado Software Summit. This is one of the best conferences I have attended in a long time, with just about 300 attendees and serious sessions with very little fluff and absolutely no product/vendor pitch of any kind. This is one conference that I can recommend to any one who value their money and time spent on conferences.

Here are the slides for my sessions:

Pragmatic REST: This session is about building HTTP APIs RESTfully.

Here is the link to download a PDF version.

RESTful Web Apps: This session is about the RESTful aspects of the web, and how certain mainstream Java web frameworks make it harder to build web apps that play nice with the web architecture. My slides for this session are not as polished as I would have liked, but well – that's all the time I have.

Here is the link to download a PDF version.

Here is the approach I used in my session at the Colorado Software Summit on REST (I will post the slides over the weekend) to find resources.

• Domain Nouns: This is the most natural approach for finding resources, but it can end up with an inconvenient resource model. For instance, the NYT Movie Reviews API has things like Movies, Reviews, Critics, Critic's picks, Reviews by reviewer identified as resources. These can provide a good starting point, but may not meet the needs of client apps, which leads to the next step.
• Composites: These are combinations of other resources, created primarily to address client app needs. Composites can also fix the urge for batching. An example is "a user profile with 5 contacts plus favorite colors plus 10 latest updates" identified as a single resource, so that the client developer can get with a single GET.
• Tasks and Processes: An example is an account transfer with some back-end process to complete the transfer at the end of the business day. Some in the audience wondered if it is RESTful to identify such an account transfer "process" (something that is typically identified as a verb). But why not? Such processes can be resources themselves with their own state and lifecycle.

Explaining "state" in "Hypermedia as the Engine of Application State" (HATEOAS) is a bit tricky, particularly when you have to do it under two minutes.

The problem is that, the word "state" means different things to different people. For most of us coming from some background in web development, state usually involves numbers, strings, booleans, and other objects stored in some place, say, in an in-memory session. For instance, every beginner-level book on web development includes a shopping cart style sample that stores the cart in an in-memory session. If we extend that notion to understand or explain HATEOAS, it would make us jump to the conclusion that, to make hypermedia as the engine of application state, the server will have to encode similar objects into some XML or such form of representation in response to each request. This line of thinking is a trap.

Here is why. Once the server includes such state in a representation, the next step for the client is to replay the state in future requests to the server. Then we are talking about exchanging those objects back and forth, and not every HTTP verb has enough room to carry that state. This line of thinking will then start to shoot holes into the notion of a uniform interface because, to fit the state in a request, the client may have to resort to POST. I can almost see message passing over POST as the next logical step. At this stage, whoever is trying to explain HATEOAS may have make some lame excuses and move on. Whoever is listening will then conclude that "yeah, this won't work for my apps".

Here is an example that I find most useful to explain the "state" in HATEOAS.

There are three pages in a UI. The first page has a link to go to the second page. The second page has a link to go to the previous page as well as the third page. The third has a link to the second page and another link to the first page.

A client starts from the first page, and then through the link on that page, goes to the second page. The fact that this page has one link to the first page and another to the third page implies that the current state of the application (i.e. the interactions) is that "the client is viewing the second page". That is what it means by hypermedia as the engine of application state. It does not necessarily mean serializing application state, such as "<page>2</page>" into representations.

I admit that I am simplifying this a bit. The point is that state does not necessarily mean some data stored in representations. HATEOAS means that representations reflect the current state of the app through links with known relations. Those links may contain opaque references to some persistent state on the server.

Why did RFC-4267 not leave room for a JSON-family of representations? For XML, RFC 3023 formally defined XML-based media types using the "+xml" naming convention, so that clients (e.g. XMLHttpRequest) can recognize any XMLish media type as long as the media type follows this convention. But not so for JSON?

A partial representation is one where the client would ask for a specific bits and pieces of a representation, such as Amazon serving a partial representation of a book containing just the table of contents, or just the reviews and comments. The problem is quite simple, and a  solution like the following would work:

GET /book/0-374-29288-4?view=toc
GET /book/0-374-29288-4?view=reviews
GET /book/0-374-29288-4?fields=reviews,comments

At Yahoo!, we call this the "view" pattern. The key thing to note here is that the names of views or fields don't necessarily refer to particular members of representations – such as elements/attributes in XML-family of representations or properties in JSON representations. It is up to the server to define what the values of those parameters mean. They could potentially mean inclusion/exclusion of different members of representations in particular media types. This way, we can let URIs remain decoupled from particular media types. I consider this important to let the system evolve to support conneg for what it is designed for.

Flickr solves the same use case by taking an extras query parameter with a list of fields to include for its search API.

Another reason we adopted this pattern for serving partial representations is that this approach lets us link to those representations, as in

<link href="/book/0-374-29288-4?view=toc" rel="view"/>
<link href="/book/0-374-29288-4?view=reviews" rel="view"/>
<link href="/book/0-374-29288-4?fields=reviews,comments" rel="view"/>

By being able to link like this, we can take advantage of HATEOAS as well as do some interesting things that only opaque URIs let us do.

Although this approach is quite common, once in a while we come across some proposals that deserve a bit more scrutiny.

The most recent approaches that I came across with are from the RESTful JSON proposal. The first is based on a new "locator" media type parameter. In this model, a client would include a header such as

Content-Type: application/json;locator=my_id[{"my_id":"1","name":"John Doe"},{"my_id":"2","name":"Jane Doe"}]

The idea of this locator is to identify a sub-resource. This is an interesting but questionable usage of the Content-Type header. I say questionable because the purpose of the Content-Type header is to indicate the media type of the entity enclosed in the body of a request or a response. Here, what is included is not just a media type of the entity. It is also encoding data, thus mixing up resource naming and resource data. In RESTful systems, we use URIs to name resources, and let headers provide metadata of a request/response or the entity enclosed within a request/response.

The same proposal includes another idea to deal with partial representations of collections of resources. That is to rely on the Range and Content-Range headers. Here is an example.

GET /Person/ HTTP/1.1
Range: items=0-1

Content-Range: items 0-1/33

...

Here, the client is asking for the first two elements of a collection using the Range header.

In HTTP, Both Content-Range and Range headers describe byte ranges. See Sec 3.12 of RFC 2616, which recognizes "bytes" as the unit of content range. RFC 2616 does allow extensions, but software that can recognize byte ranges is likely going to trip when it sees extensions like this.

Most importantly, both these approaches prevent linking. You can't claim a solution to be RESTful if you can’t use it to link to a resource or a representation.

Sanjiva says

Oh yeah we support both WS-* and RESTful services. However, they won’t meet the RESTafarian fanatics like Tim Bray’s coolaid drunkenness level of REST .. but if you want to do pragmatic work with services and support either or both of WS-* and REST then take a look at Apache Axis2 (Java & C), WSO2 WSAS, WSO2 Mashup Server, WSO2 WSF/{C,C++,PHP,Perl} etc…

Is supporting a uniform interface (REST) and a non-uniform interface (WS-*) at the same time in a given server possible without violating some or all the constraints of REST? Or, is this approach, which was expressed by several others (sorry – don’t have references handy), based on the POX interpretation of REST (i.e. transport some XML over HTTP treating HTTP as though it is just wire-level protocol)?

Apparently there is a JSON-RPC working group and a proposal to marshal RPC over HTTP. The description is quite simple:

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. It uses JSON (RFC 4627) as data format, and is transport-independent. It’s designed to be simple!

The abuse is clear from the proposed OpenSocial JSON-RPC API.

POST /jsonrpc HTTP/1.1
Host: api.example.org
Authorization: <Auth token>
Content-Type: application/json
{
"method" : "people.get",
"id" : "myself"
"params" : {
"userid" : "@me",
"groupid" : "@self"
}
}

But what is so un-simple about the right approach?

GET /people?... HTTP/1.1
Host: api.example.org
Authorization: <Auth token>

Sergey Beryozkin is wondering about

is it what actually defines Web Services ? Not only the actual technology per se but the fact that multiple businesses can do the same technology and successfully interoperate?

Will it ever happen with RESTful services ? Will it be possible for multiple companies to interoperate with more sophisticated things involved such as transactions, for ex, something which is possible to do with WS-BusinessActivity which does not really lock all involved ?

…

Or is it something which will not be ever needed in practice ?

The fact that I am using a client (i.e. the browser) that uses the hypermedia provided by my blog server to create/update representations of resources identified by URIs via a uniform interface (HTTP) demonstrates the interoperability of applications built upon the REST architectural style.

The question about transactions and REST often stems from the misconception of equating POX over HTTP to REST. Unfortunately, POX over HTTP is not the same as REST. What gets tested for interoperability under WS-* (such as understanding SOAP body/headers, serializing/deserializing different XML constructs, faults etc) is not necessarily the same for REST (implementing the uniform interface, understanding media types and hypermedia etc.)

What is striking about the WS-Empire striking back (borrowing from Mark’s post) is not the attempt to "standardize" certain new features for SOAP messages, but the apparent lack (or break-down) of a cohesive guiding principle for architecting SOAP-based web services. I’m referring to WS-ResourceTransfer here.

Let me get to the basics. According to SOAP 1.2,

SOAP Version 1.2 is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. … using XML technologies, an extensible messaging framework containing a message construct that can be exchanged over a variety of underlying protocols.

If I buy into this model, I would take it that the message describes everything – the operation/verb, the data, and any additional instructions to process the data.

But if we look at WS-ResourceTransfer, it says that

it intends to form an essential core component of a unified resource access protocol for the Web services space…

and then goes on to define a standardized technique for accessing resources using semantics familiar to those in the system management domain: get, put, create and delete.

What? One of the strongest arguments in the REST vs WS-* debate so far has been that a uniform interface (as in REST) is not adequate to describe the varieties of operations that enterprises need to do (with WS-*). But then why attempt to define a uniform interface familiar to those in the system management domain when the WS-* side concluded that uniform interfaces don’t meet the needs? Looks like a resource access spin.

Here is an addition to the list of anti-patterns that Stefan recently posted. The pattern is to let the client "think" that is using verbs other than GET and POST, but piggyback such requests over GET or POST. This was originally started by the GData folks via the X-HTTP-Method-Override header. Rails came along and baked its version for faking PUT, and DELETE over POST.

Let me start with a Rails example.

<%= link_to "Delete Image", @image, :confirm => "Are you sure?", :method => :delete %>

This is from the Rails API documentation.

Here, the intent is to let the client submit a DELETE request to delete a resource. Given that HTML forms do not support DELETE, Rails generates the following HTML:

<a href="/images/9" onclick="if (confirm('Are you sure?')) { var f = document.createElement('form');
f.style.display = 'none'; this.parentNode.appendChild(f); f.method = 'POST'; f.action = this.href;
var m = document.createElement('input'); m.setAttribute('type', 'hidden'); m.setAttribute('name', '_method');
m.setAttribute('value', 'delete'); f.appendChild(m);f.submit(); };return false;">Delete Image</a>

When clicked, this creates an HTML form with method POST, and submits it.

What good is this for? I can’t think of any. As far as HTTP is concerned, it is a regular POST and all the rules for POST apply. The browser is still submitting a POST request. The server-side may think that it is implementing a DELETE, but it is of no consequence as far as the client and HTTP are concerned.

The same is the case with X-HTTP-Method-Override. Patterns like this are misleadingly simple, and completely worthless.