What is the proper way to do REST?

Question

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?

Answer 1

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!

Bibliography

RESTful Web Services, Sameer Tyagi

REST APIs must be hypertext-driven, Roy Thomas Fielding

RESTful Web services: The basics, Alex Rodriguez

Webber REST Workflow

Answer 2

a REST bible book or something....

No bible book necessary; I had the same exact questions, and learned everything I needed or wanted to know about REST by reading these three articles:

1. A Beginner's Introduction to HTTP and REST from Net Tuts+
2. RESTful Web services: The basics from IBM developerWorks
3. RESTful HTTP in practice from InfoQ

But I want to do it right.

As you'll read in the articles above, the key is to think of the accessible pieces of your application as "resources" that can be created, retrieved, updated, or deleted using the existing HTTP "verbs": GET, PUT, POST, DELETE.

Also, know the difference between PUT and POST, and when to use them. GET, PUT, AND DELETE should be idempotent transactions, POST should not.

Also, make proper use of the HTTP status codes when communicating back to the client.