Hypermedia, links and verbs

Today I was talking to Jose Valim, about hypermedia and how links could be represented in many ways using several different media types.

One of the most common question that appears on rest-discuss every now and then is why atom, and similar, links do not include an attribute that tells the client which verb should be used to access that resource, as html does:


form action="..." method="post"


Actually, html uses the method attribute in a form not to tell how to access a resource: a resource is always retrieved through GET, always created through PUT and POST, always deleted through DELETE.

Html uses that attribute to allow the server notifies which parameters are necessary and which media type to use to retrieve (GET) or create (POST) a resource.

We typically think that the verb is necessary because otherwise clients would not know that they are supposed to do a post, i.e. for publishing a blog entry:


link href="/posts/1/publish" rel="publish" verb="POST"


That’s because the link relation identifies an action, not a resource. Thinking about resources and sticking to the uniform interface when it comes to verbs, we would have:


link href="/posts/1/publish" rel="publication"


It is quite clear that POSTint to such URI would create something, while GETting would retrieve.

In those cases, there is no need for explicit verb declaration on the link (or form).

There *might* be a need when specifying query parameters or writing input elements within a form.

Restfulie, Railsconf and New York

Restfulie 0.8 is out with a list of contributions, including new functionalities, an mvc approach which will be explained soon and support to a nicer DSL on the server and client side.

For those who are coming to Baltimore for Railsconf, Fabio Akita will present a session on Bringing more Rest to Rails with Restfulie. If you are up for a talk on REST join the session and meet us there or during the event.

I will be in Baltimore and New york until the 12th June, those who are interested in discussing the subject or coding on Restfulie can get in touch with me through my email or twitter.

Minimize coupling with REST processes

While integrating systems, implementing access or processes is typically achieved through man ordered list of steps, where one expects specific results from the server.

Expecting specific results means coupling your client to a servers behavior, something that we want to minimize.

In REST clients, and in business process modeled following REST practices, we can reach lesser decoupling factors. Imagine the following system (among others) that buys products at amazon.com:


When there is a required item
And there is a basket
But didnt desire anything
Then desire this item as first item

When there is a required item
And there is a basket
Then desire this item

When it is a basket
And there are still products to buy
Then start again

When there is a payment
Then release payment information


The above code works and can be seen running in the last video from this post. In this Rest modelled process, several types of evolutions can happen on the server, without breaking the client:

1. After adding a product to the basket, if the server renders recommendations instead of your basket, the client still achieve its goal.

2. If some products are not found, the client is still able to pay for it.

3. If the server does not have the products, but links to another system in a affiliated program, we as clients will never notice it, and buy the products.

4. If we want to achieve the same goal in other systems that understand the same media type that we do, simply change the entry point..

Note the benefits from backward compatibility, forward compatibility and we are still capable to achieve our goals without knowing the existence of some changes on the protocol. We can even compare prices without changing one line of code, everything using well known media types as Atom. RDFa support can also be implemented.

This evolution power is not achieved in traditional process modelling, and several times, compatibility is left aside. This is something that REST and hypermedia brought us.

Mapping our process in a adaptable way using hypermedia was described in an article recently for the WWW2010 proceedings.

Now let’s imagine the traditional modelling:

1. Search
2. Add
3. Search
4. Add
5. Pay

In a typical web services + business processing scenario, how would a server notify me to access another system without changing one line of code in my client? It would break compatibility.

If the server now supports a limited quantity of items in your basket, your client will also break, while the adaptable REST client adapts itself and buys what it is capable of.

If our produt or company uses those traditional paths and every change on the service implies in heavy change costs for clients, thats a hint that your project is too much coupled, and a REST client as mentioned might help.

Tradicional web services decouple a little bit more than traditional RPC, but still provide this amount of coupling that cost our companies more than they were expecting to pay.

The following presentation 6 minutes presentation shows how to avoid some of this coupling from your server.

The entire video cast on the 3rd part from Rest from scratch is here:

This code achieves its results using Restfulie 0.8.0, with many thanks to everyone who contributed maturing this release: Caue Guerra, Luis Cipriani, Éverton Ribeiro, George Guimarães, Paulo Ahagon, Fabio Akita, Fernando Meyer and others.

Thanks to all feedback from Mike Amundsen, Jim Webber and Ian Robinson.

Is your client api code already adapting itself to changes?

(update: changed some of the “Then” clauses from the dsl for easier spotting of document messages instead of commands)

The Web and Rest (Rest from Scratch – Theory 1)

Rest is not only about http and the web, but an architectural style derived from the web and others.

In this 20 minutes video, we will see how the web has been capable of scaling, providing different services and being a more effective system than other human distributed systems alike (i.e. water distribution and electricity).

We move on to describing the basic characteristics of a rest architecture and how it leverages your system.

This is the first video on the Rest from Scratch – Theory. You can watch the other Rest From Scratch – Practice videos online here.

Watch the following video at vimeo or click here.

Rest from scratch – Part 2

This 20 minutes video shows how to move from a basic REST api to one which makes use of linked resources and adds semantic values to those links.

Did your REST api do that already? Great.

Otherwise, it’s time to move ahead and decouple a little bit further your clients from your server.

Restfulie at Thoughtworks’ radar

Thoughtwork’s Radar has been released and Restfulie has made into it. Together with a few emerging architecture types, Restfulie has been apointed for “assess”.

“It is something that we believe is worth exploring with the goal of understanding how it will affect the technology impacted dimensions of your enterprise”.

Restfulie is mentioned in the same level as well accepted and up to date ideas as OAuth, NoSQL, Github.

“It is an empirical proof that the web and hypermedia can be used to orchestrate complex business activities”

There are a few videos available at vimeo for those interested in learning how to use. Jim Webber and myself are giving a talk on REST May 13th in Sao Paulo and Fabio Akita is presenting Rest using restfulie at Railsconf 2010 later next month.

Congrats to the entire commit team (Guilherme Silveira, Caue Guerra and George Guimaraes) and all contributors, specially everyone at Abril Digital who has been contributing a lot of atom related code.

REST from scratch

This is the first post on a series of examples on how to use Rails and Restfulie on the server side and Restfulie and Mikyung on the client side to create REST based architectures.

On this 10 minutes video you will learn how it is possible to make several representations of one resource available on the server side (xml, json, atom and so on) and one line of code access and parse it on the client side.

This video shows how to access those basic REST api’s as Twitters, CouchDB which are based on http verbs and multiple URIs. The following videos shall demonstrate how to access more advanced REST API’s.

If you have any questions, join us at our mailing list.

Final post… moving to blog.caelumobjects.com

This will be my final post in this blog for a while.

All posts were moved to blog.caelumobjects.com and I will keep posting over there.

Buying through REST: applying REST to the Enterprise

REST was a research result that left us with an open question, as its researcher suggested: it beautifully solves a lot of problems, but how to apply it on contemporary concerns that enterprise have?

REST Applied

After many talks, I have summed up a model, derived from REST constraints, that allows one to measure how his entire system (client and server) achieves a REST architecture.

The following video shows an example on how to start from a typical non restful architecture to adopting REST constraints and creating a buying process in any REST server.

So what is the power behing applied REST?

“Rest Applied” as I have exemplified, solves our contemporary concerns, filling the gap between Roy’s description and application’s usage, opening up a new world of possibilities.

The same way that REST ideas, although they were not called REST at that time, allowed web crawling to be an amazing client, “REST applied”, as described, can change the way our applications communicate with servers.

Why did we miss it? Because Roy’s description goes for with crawling examples, which benefit directly from content type negotiation. i.e. different languages, same resource and google post ranking it:

“In fact, the application details are hidden from the server by the generic connector interface, and thus a user agent could equally be an automated robot performing information retrieval for an indexing service, a personal agent looking for data that matches certain criteria, or a maintenance spider busy patrolling the information for broken references or modified content [39].”

But, “Not surprisingly, this exactly matches the user interface of a hypermedia browser. “… the client adapts itself to its current representation – limited to the client’s cleverness.

REST Applied takes those ideas to solve our problems, as some examples from Rest in Practice and procurement through rest.

Frameworks/libraries used

Restfulie gives better HTTP support to http libraries and provides a REST frameworks while Mikyung allows you to create your REST clients. With both of them you are ready to apply REST to enterprise problems.

Mikyung stands for “beauty capital” in Korean, in a attempt to reproduce what a beautiful rest client could look like when following REST constraints.

REST maturity model

Not yet REST

How do we achieve REST? Leonard Richardson’s model was widely commented and Martin Fowler posted on “Rest in Practice” (a book I recommend reading). But what is left out from REST in Richardson’s model and why?

According to his model, level 3 adds hypermedia support, leveraging a system through the use of linked data – a requirement for a REST architecture. But HATEOAS alone does not imply in REST, as Roy stated back in 2008.

Remember how method invocation on distributed objects allowed you to navigate through objects and their states? The following sample exemplifies such situation:


orders = RemoteSystem.locate().orders();
System.out.println(orders.get(0).getProducts().get(0));
receipt = order.payment(payment_information);
System.out.println(receipt.getCode());


But what if the above code was an EJB invocation? If navigating through relations is REST, implementing EJB’s protocol through HTTP would also be REST because linked data is also present in EJB’s code – although lacking an uniform interface.

While Richardson’s model get close to REST on the server side, Rest in Practice goes all way to a REST example, describing the importance of semantics and media type importance. The rest of the post will explain what was left out of this “Rest services” model and why, proposing a model that encompasses REST, not REST under http; while the next post, with a video, describes how to create a REST system.

What is missing?

“The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations.“.

Did the previous code inspect the relations and state transitions and adapted accordingly?
It did not choose a state transition, it contains a fixed set of instructions to be followed, no matter which responses are given by your server. If the API in use is http and the server returns with a “Server too busy” response, a REST client would try again 10 minutes later, but what does the above code do? It fails.

We are missing the step where REST clients adapt themselves to the resource state. Interaction results are not expected as we used to in other architectures. REST client behavior was not modelled on Richardson model because the model only thought about server side behavior.

This is the reason why there should be no such a thing as “rest web services” or “rest services”. In order to benefit from a REST architecture, both client and server should stick to REST constraints.

Richardson’s server + http model

Semantic meaningful relations are understood by the client, and because of that we need a model which describes how to create a REST system, not a REST server.

An important point to note is that this model is pretty good to show a REST server maturity over HTTP, but limiting REST analysis both to server and http.

A REST architecture maturity model

For all those reasons, I propose a REST maturity model which is protocol independent and covers both consumer and provider aspects of a REST system:

Rest Architecture Maturity

Trying to achieve REST, the first step is to determine and use an uniform interface: a default set of actions that can be taken for each well defined resource. For instance, Richardson’s assumes HTTP and its verbs to define a uniform interface for a REST over HTTP architecture.

The second step is the use of linked data to allow a client navigate through a resource’s state and relations in a uniform way. In Richardson’s model, this is the usage of hypermedia as connectedness.

The third step is to add semantic value to those links. Relations defined as “related” might have a significant value for some protocols, but less value for others, “payment” might make sense for some resources, but not for others. The creation and adoption of meaningful media types allows but do not imply in client code being written in a adaptable way.

The fourth step is to create clients in a way that decisions are based only in a resource representation relations, plus its media type understanding.

All of the above steps allow servers to evolve independently of a client’s behavior.

The last step is implied client evolution. Code on demand teach clients how to behave in specific situations that were not foreseen, i.e. a new media type definition.

Note that no level mentions an specific protocol as HTTP because REST is protocol independent.
The following post will describe one example on how to create a REST system using the above maturity model as a guide.