REST – What Is the Proper Way to Implement REST?

implementationsresourcesrestsoa

Everybody nowadays does SOA, even if some don't actually understand what is all about. So they do it wrong. Using that as an analogy I know what REST is (or at least I think I do) and want to do some of it. But I want to do it right.

So my question is what's the proper way to do REST?

Best Answer

Well, there are a lot of ways to learn how to build a RESTful web application and no, there isn't a unique right way. RESTful is not a standard but it uses a set of standards (HTTP, URI, Mime Type, ...).

Start with this: How I Explained REST to my wife

Then, proceed with this: RESTful Web Services Cookbook

And then put your entire effort to develop web applications because the best way to learn is doing experiments and you can learn so much from your mistakes ;)

Don't worry if your first web apps won't be completely RESTful: you will find the way to do it!

So, quoting Obi-Wan Kenobi, "may the force be with you!" ;)

EDIT

Ok, let me be more specific. You wanna make some RESTful webapp, huh? Well, as I said there are many ways to do it but this is the main guideline.

Definition

REST (Representational State Transfer) is a software architecture's style for distributed system (like WWW). It is not a standard but it uses a set of standards: HTTP, AJAX, HTML, URI, Mime Type, etc. We are talking about representation of a resource, not about a resource itself. Taken from 'How I explained REST to my wife':

Wife: A web page is a resource?

Ryan: Kind of. A web page is a representation of a resource. Resources are just concepts.

Architecture's Constraints

Client-Server: client and server are separated by the Uniform Interface (described below).
Stateless: server-client communication is done without saving a particular client state on the server.
Cachable: the client might have a cache of responses of requests already made.
Layered System: the client doesn't know if it's directly connected with an end-server or if the communication is done through intermediates.

Uniform Interface

Resources' Identification: each resource has to be identified by a URI.
Protocol: in order to get in communication client and server, a protocol has to be done before. Each request might have the right MIME Type (application/xml, text/html, application/rdf+xml, etc.), the right headers and the right HTTP method (see CRUD description below).

CRUD

Ok, we saw that to identify resources we can use URI, but we need something else for the actions (add, modify, delete, etc): a great welcome to CRUD (Create, Read, Update and Delete).

Create {HTTP: POST} {SQL: INSERT} => create a new resource
Read {HTTP: GET} {SQL: SELECT} => get a resource
Update {HTTP: PUT} {SQL: UPDATE} => modify a resource
Delete {HTTP: DELETE} {SQL: DELETE} => delete a resource

Now, concerning PUT and DELETE, some tech problems could appear (you'll get them with HTML form): often developers bypass this problem using POST for each 'PUT' and 'DELETE' request. Officially, you have to use PUT and DELETE. By the way, do what you want. My experience pushes me to use POST and GET every time.

--- Next part should be used but it isn't a REST's bond: it concerns Linked Data ---

URI

Abstract URI from technical details! Say goodbye to URI as follows:

http://www.example.com/index.php?query=search&id=9823&date=08272012

Re-design URI! Take the link above and change it as follows:

http://www.example.com/search/2012/08/27/9823

That's much better, huh? It could be done by:

server application: a root file that routes each request.
server web: .htaccess file plus rewrite rules
client application: HTML5 history object or fragments (also Twitter uses fragments: http://www.twitter.com/#!/__wilky__)

Another thing: use different URI to represent different resources:

http://www.example.com/about (that's the resource)
http://www.example.com/about.html (that's the HTML representation of the resource)
http://www.example.com/about.rdf (that's the RDF representation of the resource)

Pay attention: about.html and about.rdf are not files! They could be the result of an XSLT transformation!

Content Negotiation

If you've reached this point, congratulations! Probably, you're ready to get more abstract concepts because we're entering in the Semantic Web technical details ;) Well, when your client wants a resource, it typically makes the following request:

GET http://www.example.com/about
Accept: application/rdf+xml

But the server won't respond with the about.rdf because it has a different URI (http://www.example.com/about.rdf). So, let's have a look to the 303 pattern! Server will return this:

303 See Other
Location: http://www.example.com/about.rdf

And the client will follow the link returned as follows:

GET http://www.example.com/about.rdf
Accept: application/rdf+xml

Finally, the server will return the resource requested:

200 OK
about.rdf

Don't worry: your client application won't do anything of this! The 303 pattern must be done by the server application and your browser will do the rest ;)

Conclusion

Often the theory is far, far away from the practice. Yeah, now you know how to design and develop a RESTful application but the guideline above is just a hint. You will find your best way to build web applications and probably it won't be the same as theory wants. Don't give it a damn :D!