RESTful best practices

Jean-Baptiste Escoyez & Nicolas Jacobeus FOSDEM 08 Ruby on Rails DevRoom 24 February 2008

Frailers.net

Outline

REST REST in Rails REST in Rails: Best practices

REST

REST

What is REST? How does REST work? Why REST?

REST

What is REST?

Its about communication between computers Its about designing the architecture of your applications

REST What is REST?

Its about communication between computers

Web services!
SOAP / XML-RPC => communication REST => communication + standardisation

REST What is REST?

Its about architecturing your application

esis by Roy Fielding (2000)
Architectural Styles and the Design of Network-based Software Architectures

REST applies some constraints to the architecture of your application e interface is the same for humans and computers
(by the way: REST means Representational State Transfer... I think)

REST What is REST?

How does REST work ?

Everything is a resource 4 basic requirements for a RESTful system

REST How does REST work?

e concept of resource
Resource = thing exposed by the system to the outside world Everything is a resource
http://www.frailers.net/users/1 http://www.frailers.net/users/1/memberships

Independent from its representation

user.html => http://www.frailers.net/users/1 user.jpg => http://www.frailers.net/users/1

REST How does REST work?

When is a system RESTful ?

Addressability Statelessness Connectivity Uniform interface
4 standardized actions: GET - POST - PUT - DELETE Safety (GET) Idempotence (PUT-DELETE)
REST How does REST work?

So, why REST ?

Standardisation is good Why use so many dierent functions when you always do the same (CRUDing objects) Why separate the logic for computers and humans ? (segregation is evil) Statelessness => scalability and decoupling

REST Why REST?

Enough for this theoretical HTTP stu!

is is a DevRoom about

, right ?

REST Why REST?

REST in Rails

(Not on Rails !)

REST in Rails
Addressability: RESTful routes Representation independence: respond_to Nesting resources Developing REST clients ...and some tasty Rails sugars

REST in Rails

Addressability : Routes
RESTless VERB HREF
POST GET POST ????
/users/create /users/1 /users/1/update /users/1/delete

RESTful VERB URI

POST GET PUT DELETE
/users /users/1 /users/1 /users/1

REST in Rails Routes

Addressability : Routes
map.resources :users

Resource
/users /users /users/1 /users/1 /users/1

Verb
GET POST GET PUT DELETE

Action
index create show update destroy

REST in Rails Routes

RESTful Rails controller

A RESTful controller has 7 standard actions Each controller deals with a resource (user) and its collection (list of users)

REST in Rails Routes

Representation independence: respond_to

Based on:
HTTP Accept Header Format extension
http://www.frailers.net/articles/24/comments/1.html http://www.frailers.net/articles/24/comments/1.js

REST in Rails respond_to

Making REST clients : ActiveResource

class Project < ActiveResource::Base self.site = http://localhost:3000 end projects = Project.find(:all) new_project = Project.new(:name => My new project) new_project.save

REST in Rails ActiveResource

Nested resources
http://www.frailers.net/articles/24/comments/1 http://www.frailers.net/articles/24/author ActionController::Routing::Routes.draw do |map| map.resources :articles do |article| article.resources :comments article.resource :author end end

REST in Rails Nested resources

More rails sugars

Scaolding
script/generate scaffold article title:string \ body:text published:boolean

Helpers
link_to @article form_for @comment do |f| ... end redirect_to @article

Authentication RESTful authentication plugin

REST in Rails Sugars

To sum up...
Using REST in Rails is good lightweight controllers API given for free Rails is opinionated implementation of REST is not perfect

REST in Rails Conclusion

Best practices

Best practices

Design methodology Real-life examples

Best Practices

Disclaimer!

Maybe best is an overstatement

(is sounded great for the call for papers)

ere are always dierent solutions

Best Practices Disclaimer

Design methodology

Knowing Rails resources API is great, but not sucient e big question:

what resources do I choose ?

Best Practices Design methodology

Classic beginners mistakes

strictly mirroring your ActiveRecord data model to choose your resources thinking all 7 actions should be written for each and every resource and, of course, adding custom methods if the standard ones dont t

Best Practices Design methodology

Resources are not models

Well, to be fair, then can (and usually) represent models But also:
Relations States Events
(DHH told me so)

Best Practices Design methodology

Nouns are the new verbs

Change your way of explaining a scenario, an action Use a noun to describe the action e noun given to your scenario is the resource youre looking for
A user subscribes to a group e project is validated by its owner e user deactivates his account A subscription is created A project validation is created A user account activation is deleted

Best Practices Design methodology

7 is not a strict target

Resources can be read-only Sometimes, actions are meaningless:
update an account activation ? really ? destroy a page view ? why ?

Best Practices Design methodology

Dont be tempted!
Rails allows extra, custom methods to be added to controllers, if you really need them But youll lose all what you were trying to do in the rst place (no uniform interface, etc.) I have never needed that (except, maybe...) If you do need that, its probable that youd better rethink your architecture
Best Practices Design methodology

OK, you want real-life examples

Adding/removing members from a group Dealing with object workows Multi-step edition wizard Managing a shopping cart Manipulating several resource in one request

Best Practices Real-life examples

Adding / Removing members from a group

Best Practices Real-life examples

Adding / Removing members from a group

Best Practices Real-life examples

Dealing with object workows

Consider a CMS with all sorts of documents Each document has a status: draft, reviewed, published, ...

Best Practices Real-life examples

Dealing with object workows

Or another way : only update the document

depending on the business logic, this can be considered overloading

Best Practices Real-life examples

Multi-step edition wizard

A complex model needs to be edited in 3 steps, in a precise order

Best Practices Real-life examples

Multi-step edition wizard

All these steps are dierent, partial representations of the same resource Just GET the resource and put the step as a parameter Update the resource at each step... and redirect to the next step representation

Best Practices Real-life examples

Multi-step edition wizard

Best Practices Real-life examples

Managing a shopping cart

We keep in the database the state of the shopping cart for each user:
/users/21/shopping_cart_items

Yes, but I dont want the cart to be persistent

Delete from the database when the user logs out
Best Practices Real-life examples

Manipulating two resources simultaneously

Youre not manipulating two resources Youre manipulating a couple of things e resource is the couple Create guy, create girl => Create couple

Best Practices Real-life examples

Manipulating two resources simultaneously

If you still need to do it in several steps... CREATE a Transaction resource PUT the rst part PUT the second part commit (PUT committed) or revert (DELETE)
Best Practices Real-life examples

ere are still some limitations...

I want to choose items to delete from a list with checkboxes DELETE only works for a single resource at a time What youre doing is updating the parent resource If theres no parent resource, youre screwed

Best Practices Real-life examples

ank you!

Its lunch time! Lets eat! Lets create some LunchEatings !

POST /lunch_eatings