Rest – the proper way of nesting resources in REST model

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

One of the core ideas behind REST is that each URL provides a representation for a single resource (although that resource can be a collection that gives information about other resources).

If you want to get information about multiple sensors, where you don't know/care which device each sensor is connected to, the canonical way is to provide a top-level sensors resource: GET /sensors. This would give you all sensors in the system. If you wan't to restrict the list in some way, you use query parameters:

GET /sensors?device=d1,d2,d7,d30,d45,d500&type=temperature

would give you the temperature sensors connected to the listed devices.

If you do care which device each sensor is connected to, there is no way around performing multiple requests, one for each device.