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.

Moving URIs around: how careful should I be?

Entry Points

In the human web, the entry point is a strong coupled URI.
Changing your company’s entry point from http://www.caelum.com.br to http://www.newcaelum.com.br without notifying your
clients will cause serious damages to those using your website.

The same holds for REST applications. Entry points to your system are strong coupled and
changing it without notifying your clients will break their system usage.

Entry point’s should not change without noticing your clients.

How can my clients become aware of the URI change?

Once you have published your new URI, set your old URI response to “301 – Moved Permanently” and set the header “Location” with
the appropriate location. Once 301 is received your clients can cache this response forever, changing their entry point configuration, because the move is permament.

By adding a proxy server to your system, the Moved Permanently response will be cached.
Restfulie will automatically redirect the user to the new URI upon receiving 301 on GET and HEAD:

product = Product.from_web 'http://www.caelum.com.br/product/2'
# received a 301, went to the new Location

If the request is anything but GET or HEAD, the user has to explicetely define its intention on following 301:

# explicitely following 301 on other verbs
class Product
	uses_restfulie
	entry_point_for.create.at 'http://www.caelum.com.br/product'
	
	follows.moved_permanently
end

product = Product.remote_create Product.new
# received a 301, re-posted it to the new uri, received a 200

Internal elements

In the ideal human web, all gettable resources are bookmarkable therefore any changes to those resources also
imply possible damage to your clients. After accessing http://www.caelum.com.br for the first time, if I access a ruby training,
I get to http://www.caelum.com.br/cursos/rr-71. I can use this address in several ways, i.e. bookmarking or sharing it.
If the courses URI’s changes, bookmarked URI’s will not work: the user will only find it out after trying it.

Once he has got a 404, the user will go back to the entry point and restart his procedure to
access the previous (invalid) bookmarked resource if the server does not answer with a Moved permantently response.

That’s what we do when our bookmarks break.

Again, the same holds for REST applications. In order to keep the benefits form Addressability, once published, one has
to keep his URI’s valid forever: either responding with its content, a See Other (303) or a Moved Permanently (301) response.

REST bases itself in addressability and therefore it is ok to bookmark any resource URI in the client system:
if you believe some your resources will not be bookmarked, it is ok to move them without prior notice, but remember, by
thinking that your resources were not bookmarked, you have accepted to lose one of REST’s benefits.

Client’s can always go back to the entry point and navigate through the previous executed procedure to retrieve the new URI,
but if he has to, it means that you broke one of your clients expectations.

302 and 303

Two other possible responses are 302 Found and 303 See Other.

While 302 means a temporary move, the client not supposed to cache the Location header as the new location
for the resource unless explicitely specified. Restfulie deals with it the same way as it does for 301:
you should notify Restfulie to follow 302 responses for verbs other than GET and HEAD>

When receiving a 303, the user should retrieve the resource at the new location with a GET verb.
This response allows the server to respond to a POST request by notifying the client to redirect to
the new resource URI – or any other desired one – with a GET.
The 303 response itself must not be cached.

Restfulie follows all 303 responses by default.

Summing up

No matter believing or not that your client will not cache your internal URI’s, the HTTP application protocol allows him to do it,
so in order to allow your clients to evolve appart from your own evolution, do not change the addresses
without keeping a proper Moved Permanently (301) response at those URI’s.

Internal element’s patterns might not be shared, but remember: every published resource should answer properly if they move.