36

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?

5
  • 1
    Stack Overflow 'rest' tag wiki seems to be as close as it gets to canonical resource in the context of Stack Exchange network
    – gnat
    May 23, 2012 at 16:41
  • 17
    I just shut my eyes for a while...maybe go for a bike ride and then lay down. May 23, 2012 at 16:44
  • Isn't REST basically just using a url such as mydomain.com/accounts and an HTTP verb to invoke an operation? Where the verb indicates whether you want to get, create, update or delete data? When I think REST that's what I think of. May 23, 2012 at 23:56
  • 2
    @Nick, that is the most common interpretation, the 'real thing' is a lot harder to grok, and (as far as I can tell) a lot harder to find actually implemented anywhere... (see Wilk's answer)
    – Benjol
    May 24, 2012 at 13:49
  • 3
    @Nick your understanding isn't REST, it is RPC over HTTP.
    – user7519
    May 24, 2012 at 14:02

2 Answers 2

30

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:

Another thing: use different URI to represent different resources:

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

8
  • 1
    You might consider adding this link, which is the most complete guide I've come across.
    – Benjol
    May 24, 2012 at 13:47
  • I've seen PUT and POST used with their meanings swapped (in relation to your answer): POST -> create, PUT -> update. Any idea which meaning is more widely used?
    – Andres F.
    May 24, 2012 at 15:25
  • @Andres F.: jcalcote.wordpress.com/2008/10/16/… says: Create = PUT iff you are sending the full content of the specified resource (URL). Create = POST if you are sending a command to the server to create a subordinate of the specified resource, using some server-side algorithm. Update = PUT iff you are updating the full content of the specified resource. Update = POST if you are requesting the server to update one or more subordinates of the specified resource.
    – Wilk
    May 24, 2012 at 15:33
  • @Benjol: I'm going to edit with your suggestion ;) Thanks!
    – Wilk
    May 24, 2012 at 15:33
  • 1
    @Wilk Some many things to consider! Probably why nobody gets this right :P
    – Andres F.
    May 24, 2012 at 15:51
5

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.