RailsConf 2007: Doing REST Right

Scott Raymond’s “Doing REST Right” session was a highlight for me at the just-concluded RailsConf. An experienced creator of REST-based solutions, Raymond shared an overview of REST, outside the context of rails, and an invaluable FAQ. Here are my notes from that session.

Doing REST Right – Scott Raymond, Firewheel Design

Description: Rails helps developers build REST-style web services in many ways, but important design decisions remain for each application. In this talk, we’ll go beyond the basics and tackle the practical questions that arise when implementing a modern web service in Rails.

Come unto me, all ye that labour and are heavy laden, and I will give you REST – God

Recognize rest principles in what you’re already doing. Apply them to your whole process.

Orthodoxy (right teaching, right beliefs, right thoughts) versus Orthopraxy (right practice)

Orthodoxy

Roy Fielding’s Thesis defined REST (Representational State Transfer)

All models are wrong but some are useful. George Box

Leaky abstractions.

Diagrams are wrong but useful in representing complex, real-world systems. Same thing with abstractions.

REST Isn’t

• Pretty URLs

• CRUD

  http	crud	sql
  post	create	insert
  get	retrieve	select
  put	update	update
  delete	destroy	delete

• tools for organizing your application code
  • respond_to
  • map.resources

• http
• a protocol
• an architecture

REST is…

• the architectural style of the web

• Roy Fielding’s Hierarchy

  Abstract	Communication Theory
  —	REST
  —	Web Architecture
  Concrete	Implementation

• A resource is anything that can be named
• A resource is an object with a couple of contraints – can only implement a very small number of methods, same for all resources
• you don’t access a resource—you access a representation of it. (respond_to with format.xml, format.txt, etc.)

Orthopraxy

• Identification (Address)
  • My name is URL.
• Interaction (Method or Verb) – the uniform interface, uniform small set of methods
  • safety—has no side effects, incurs no obligations (get is the only method that is safe by definition)
  • idempotent—applying a function once returns the same value as applying it multiple times (get, put and delete)
  • post is neither safe nor idempotent => reserve it for when you need it
• Content (Data, Body of Request)
  • REST pushes all of the complexity into content, out of identification and interaction
  • standards
    • messages should be self-descriptive, like html
    • look for content types that map to your application domain
      • instead of to_xml, use an established type.
      • for users do vcard instead of your arbitrary user xml

Questions in SCO’s Experience

• How do I update several resources at once? Like a to-do list application with a bunch of “finished” checkboxes…
  • Scope this request to a set of resources, using the URL
  • create a url that names that superset, then update them all (one resource) with one request

• How can I do partial updates? Like a person resource, changing just the name…
  • Scope in the url => give names a url (“people/5/name”), then post to that resource

• I’m special; I need more than GET/POST/PUT/DELETE semantics.
  • You’re wrong. You can model any problem in REST. The uniform interface is sufficiently general.

• How should I do authentication?
  • cookies force application state into the server
  • how about HTTP Basic? Makes each request self sufficient. Guards against restart, but UI sucks. Password is in cleartext with every request.
  • HTTP-Digest => eh, not quite.
  • use cookies, but make each request self-sufficient with its own session information

• Should I include content-type info in the URL?
  • Opinions have changed over the past year.
  • Previously => No, and you get network effects. But you can’t link to a specific representation, only the default representation.
  • URLs are UI, don’t let rails force your hand.
  • Now => Yes. gets you better page caching.

• What about reliability?
  • with posts, you divide them into 2 phases
    • Post to a factory method that creates a new url
    • Post (commit) to that fancy url.

• What about concurrency?
  • Use entity tags

• What about transactions?
  • Still a scope question => make a new URL that represents the full transaction.

• I need more than one representation with the same media type.
  • avoid using a generic media type, make your own