Doing REST Right

“Come unto me, all ye thatlabour and are heavy laden,and I will give you REST.” –God

Doing REST Right Scott Raymond Firewheel Design- Thanks for being here, lets get started.- My name is Scott Raymond, I’m with a company called Firewheel Design, and I’m talking today about Doing REST Right.- Let me start with a question or two. First, raise your hand if you have some idea of what REST is, even very roughly. Okay, great. Now, raise yourhand if you have built a RESTful application.- I have good news...

Congratulations! Sort of!I suspect that, in fact, every single hand in this room should be raised. Thats because if youve ever put a single HTML page on the web, you havedone REST. Congratulations! You can add another bullet point to your resume!- Thats the surprising thing about REST -- its so prevalent that we hardly even see it. But in fact, it is the default way that the web works.- So if youre already doing it, why are we even here? The answer is that we could all be doing it so much better. The trick is ﬁrst to recognize howweve been following some of the REST axioms by accident all along, and then well start to see how weve been falling short in other areas.- Now before we really get started, let me give you the plan.

Orthodoxy & OrthopraxyTheres an important distinction between _orthodoxy_ and _orthopraxy_. Orthodoxy roughly means "right teaching" -- having the right _ideas_,thinking the right thing, believing the right thing. Its about whats in your head. Orthpraxy, is a less common word. It means "right practice" -- doingthe right thing, behaving correctly, taking the right action. Both are important, but orthodoxy alone isnt worth much if its never put into practice.Like any good orthodoxy...

Like any good orthodoxy, REST has its prophets and its holy texts. (This is a picture...) Whether or not you’ve heard of this guy or read this text, bynow Id guess that most of you have heard some dose of REST orthodoxy, if only just from Rails blogs.So for the purposes of this talk, Im going to try to move pretty quickly from the theoretical to the practical. For the most part, Ill assume that youalready have the orthodoxy -- that you believe, or at least are willing to grant, that REST is a good thing. REST-style applications are rightfully seenas putting the "web" back into "web services". And you have some idea of the “why”. So what I’m going to focus on is the “how”.But real quick I want to throw out one other guideline.

“All models are wrong, but some Text are useful.” ―George BoxOne thought Id like you to keep in mind through this presentation -- for that matter, through every presentation during the rest of this conference.Its encapsulated in this quote by George Box.You’ve heard this before called "the law of leaky abstractions" and "the map is not the territory". Right? So for example here’s this famous map...

So for example heres this famous map of the London tube, where they have conveniently distorted things so that all of the lines are straight, anddont overlap too much, and the stops are evenly spaced.

And then heres a version thats geographically to scale. Much more hairy, very hard to read in the middle, and very inefﬁcient with whitespacearound the outside.Now, its tempting to say that this map is the *right* one, but the other map is the *useful* one. But Id challenge you to see it differently: *both* mapsare "wrong". After all, both of them, in some way, purport to compress and entire dynamic city into a few megapixels! But they are both useful. Andfor a given purpose, theyre each useful to different degrees.

“All models are wrong, but some Text are useful.” ―George BoxSo, when we talk about any kind of model -- not just maps, but any kind of model for understanding the world, it necessarily involves some kind ofsimpliﬁcation, some loss of resolution. Thats a feature, not a bug. Models allow us to understand and work with an inﬁnitely-complex "real world"by conveniently ignoring certain details. And so competing models shouldnt be necessarily be judged by their precision, but by their usefulness.REST, as a model of the web, is no different. It glosses over certain realities in order to provide an idealized model of how the web works.Now, my intent is to make this talk as practical as I can, but Im already getting all meta on you, so Im going to *try* to breeze through this next partpretty fast. But I want to talk about REST as the model of the web, because that theory will inform the practical questions we need answers to.

What REST Isn’t • Pretty URLs • CRUD • respond_to • map.resources • HTTP • A protocol • An architecturePretty URLs. Theres nothing about /users.php?id=123 that violates REST.

What REST Isn’t • Pretty URLs GET http://example.com/users.php?id=123Here’s an easy misconception to put to pasture.Theres nothing about this URL that violates REST. Ugly, sure, but judged as REST, it’s completely ﬁne.

What REST Isn’tCRUD. Rails seems to say that REST==CRUD. And at ﬁrst glance, its an easy reduction to make. SQL SELECT maps readily to HTTP GET, andSQL DELETE maps pretty well to HTTP DELETE. But after that, things start to fall apart.

HTTP CRUD SQL POST Create INSERT GET Retrieve SELECT PUT Update UPDATE DELETE Destroy DELETEHere’s the standard table showing how REST maps to CRUD.The problem is that this isn’t quite right. For example, PUT isn’t strictly for updating existing resources -- it can also create new ones. Same withDELETE -- it’s perfectly valid to send DELETE for some resource that doesn’t exist. And the semantics of POST are signiﬁcantly more vague thansimply creating -- it can also be understood as “append”, or even more generally, just “process this”.

? HTTP POST GET PUT DELETEHere’s the standard table showing how REST maps to CRUD. CRUD Create Retrieve Update Destroy SQL INSERT SELECT UPDATE DELETEThe problem is that this isn’t quite right. For example, PUT isn’t strictly for updating existing resources -- it can also create new ones. Same withDELETE -- it’s perfectly valid to send DELETE for some resource that doesn’t exist. And the semantics of POST are signiﬁcantly more vague thansimply creating -- it can also be understood as “append”, or even more generally, just “process this”.

What REST Isn’t • respond_to • map.resourcesrespond_to and map.resources. Rails has done a ton to embrace REST, and as a result, some developers are conﬂating whats *actually REST*with Rails implementation of REST. In fact, Ive been guilty of this myself -- I wrote a blog entry last year called "Refactoring to REST" which impliedthat you could make your application RESTful just by rewriting your routes.rb ﬁle to use map.resources. Along the same lines, REST isnt reallyrelated to how your organize your actions in your controllers, although designing your application with REST in mind does *help* you keep yourcontrollers nice and tidy.

What REST Isn’t • HTTP • A protocol • An architectureHTTP. This one might be a bit of a surprise, because HTTP and REST are kind of incestuous. REST and HTTP are at two different levels ofabstraction. HTTP is probably the most RESTful protocol, largely because REST was a post-hoc description of early HTTP, and HTTP 1.1 wasdesigned with REST in mind. But its entirely possible to judge the RESTfulness of other protocols, or to design new protocols with REST principlesin mind.A protocol or a standard. Theres no spec to implement or suite of tests to pass. But REST systems *rely* on standards all over the place -- in thecase of the web, URLs provide a standard addressing mechanism, HTTP provides a generic interface, and any number of standard media types areused for the content.An architechture. from REST book: "Thats because it presents REST not as an architecture but as a way of judging architectures. The term"RESTful" is like the term "object-oriented". A language, a framework, or an application may be designed in an object-oriented way, but that doesntmake its architecture the object-oriented architecture."One last one thats not on this list: REST is not really comparable to SOAP. They arent even really the same kind of thing. comparing REST withSOAP is like comparing object-orientation with some particular language.

So What is REST?Obviously, REST is an acronym, but it might as well not be, because knowing what it stands for doesnt really help understand what it is. So Im noteven going to bother you with what it stands for. Instead, let me throw out as succinct of a deﬁnition of REST as I can, and then Ill unpack it a bit.Here it is: REST is the architectural style of the web.Okay, so it’s not an architecture, but it’s an architectural style? Spitting hairs, huh?

So What is REST? the architectural style of the webObviously, REST is an acronym, but it might as well not be, because knowing what it stands for doesnt really help understand what it is. So Im noteven going to bother you with what it stands for. Instead, let me throw out as succinct of a deﬁnition of REST as I can, and then Ill unpack it a bit.Here it is: REST is the architectural style of the web.Okay, so it’s not an architecture, but it’s an architectural style? Spitting hairs, huh?

ABSTRACT Communication Theory REST Web Architecture Implementation CONCRETERoy said thisabout RESTs place in the world: "Communication theory is a lot more abstract than REST, REST is a lot more abstract than WebArchitecture (URI, HTTP, HTML, ...), and Web Architecture is somewhat more abstract than any current implementation of that architecture(Apache httpd, Mozilla Firefox, etc.). And yet they all need to inﬂuence each other, in various ways, when we attempt to design changes to a livingsystem."So take a look at that. Its saying that REST is pretty high up on the abstractness scale. The upshot?

More what you’d call “guidelines” than actual rules.You cant bottle REST, or sell it, or even implement it, per se -- its not a product, a protocol, a format, a speciﬁcation, a standard, or a stack. Its astyle. An architectural style. And as such, there is not really a deﬁnitive, black and white, concrete instance of REST -- not even in theory.In theory, you could come up with a perfect, to-the-letter implementation of HTTP, and essentially prove that it was perfect. Thats not true of REST,because it deals at a higher level of abstraction. As such, particular implementations are judged on their *degree* of RESTfulness.So REST gives us these guidelines. And in some way, all of them center around the concept of Resources.

What’s a Resource?Simple answer: anything that can be named. Im a resource, youre a resource. "The weather where I am right now" is a resource, too (notice howthats not static -- its constantly in flux, and it depends on where Im standing. But it can be named, so its a resource. There could also be anotherresource, called "the weather in portland on the morning of May 18". One of those resources changes over time, and the other will never change.Even though they both have the same value right now, theyre separate concepts, and so theyre separate resources.- If you want to think of REST in object-oriented terms, resources are just objects, except that they all have to have the same, small number ofmethods. The key argument of REST is that that small number of methods is sufficiently general for anything youd want to do. There are tradeoffswith that approach, to be sure -- REST does not claim to be the one true architectural style. But if what youre building is an internet-scaledistributed application, the REST style offers a lot of benefits.- One other key element is the distinction between resources and representations.

Representations, shadows in Platos cave.

IDENTIFICATION ADDRESS INTERACTION METHOD CONTENT DATAThe nuts and bolts of doing REST right happen along three aspects.- The first is _identification_, or _address_, or _scoping_ information. This is the part that answers the question, what is being acted upon?- The second aspect is _interaction_ or _method_ information. This is the part that answers the question, what action is being taken?- The third aspect of any message scheme is the content, or data, or media type.- Lets buzz through these three aspects one by one. Okay, so well start with the easiest part first, identification. In REST, identification is done withURLs, which are just names.

My Name is URL.HTTP methods are like verbs. URIs are like nouns. I.e., names for things.Remember, the name is not the thing itself.So identiﬁcation is easy; lets move on to interaction.

The Uniform InterfaceIn most message schemes (like SOAP, or OO programming in Ruby), the interaction aspect is virtually unconstrained -- each type of object supportsits own vocabulary of interactions (i.e., method names). But in REST, this spaces is restricted to a small set of generic, pre-deﬁned interactions; ifyou hear people talking about the "uniform interface", this is what theyre talking about.- Now, the REST style doesn’t actually say that those methods must be GET, POST, PUT, and DELETE. It just says that there should be a small setof methods that are the same for every resource. But on the web, those are the methods we’ve got, so lets talk through them a bit.- We’re all pretty familiar with GET and POST, and we know that the difference between them has something to do with “safety” and “idempotence”,but those terms feel vague.

Is it safe?! Is it idempotent?!- GET is the only method that’s safe. And GET, PUT, and DELETE are all idempotent.- Safe means no side effects, “incurs no obligations.”- idempotent means that performing the action many times has the same effect as performing it once. like abs.- POST neither safe nor idempotent. is the most general, the bluntest, of the HTTP methods, and therefore the most powerful, and therefore the oneto be most careful with. You can cram almost anything into POST, but you shouldnt. Use it as the method of last resort.

ContentSo of the three aspects that REST deals in, we’ve looked at Identiﬁcation and Interaction, and seen that the path is pretty well-paved: you alwaysuse URLs for scoping information, and always use the uniform interface for interaction.- That leaves the third spoke, content. And if youre doing it right, the third slice is where you should be spending most of your effort, becausecontent types are hard, and open ended. REST intentionally pushes all of the hard problems into this slice.- The ﬁrst key word here is standards. And that’s where most Rails-based REST APIs, including ones I’ve built, need improvement. This is wheremy personal opinions diverge most from Rails’ opinions. to_xml is like scaffolding -- it’s great to get you up and running, but probably not whatyou want in the end. Never invent a new XML vocabulary if you can avoid it.- Second key point about content: it should contain links. This is whats referred to when people say "hypertext as the engine of application state."To get abstract on you, you can view the web as one big state machine, and the "page" youre on tells you about all of the other application statesthat you can move to, via links. (Refrain (repeat this with other key tenets elsewhere): if your content doesnt have a lot of HREFs, youre not doingit right. [where does this leave standard-but-non-hypertext media types, like vcard?]).- So now I’d like to propose some typical questions that Rails developers will face when trying to build RESTfully.

How can I update several resources at once?- For example, say youve got a todo list, with checkboxes. One POST of the form needs to update multiple resources, so what URL does it target?- Youre wanting to scope a request to something other than one resource. There’s the clue, the keyword “scope”.- So you need to give that resource a name. Where do names belong? In URIs! so the solution is to make up a name (a URL) for the scope thatyoure wanting to update, and then PUT to that.

How can I do partial updates?is it in the semantics of PUT that the PUTted representation will be identical to what can be GETted immediately thereafter? in other words, is itokay for me to PUT a partial invoice rep, or a full one with some amount of invalid information? or should those requests result in an error? This isboils down to a scoping problem -- youre wanting to address a subset of some resource. where does scoping information belong on the web? inURIs! so the likely solution is to make up a name for the scope that youre wanting to update, and then PUT to that. I say you PUT a partialrepresentation. some people disagree, saying you should only PUT a full representation. (does HTTP or the thesis address this?)

I’m special; I need more than GET/POST/ PUT/DELETE semantics."But my model is different!". You are not a special or unique snowﬂake.- should I build another protocol?- should I add a new HTTP method?- answer 1: tough shit. youre wrong, it can be modeled with the uniform interface, its sufﬁciently general.

How should I do authentication?- Cookies are often frowned upon in REST circles, because they’re so often abused. Think of the old Rails session mechanism.- HTTP basic auth kinda blows. HTTP digest is better in some ways.- Cookies aren’t necessarily bad. The new Rails default is to store sessions entirely in the cookies -- not just a session ID, but the whole sessiondata. This rocks. It means that by default, your session-based auth is RESTful.- But for non-browser clients, you’ll probably want Basic or Digest as well.

Should I include content-type info in the URL?- answer 1: no. answer 2: yes- Its a trade-off. if you do, you can create straight browser links to speciﬁc representations, which is pretty essential. but the downside is thatyoure limiting the network effects. So proceed with caution- This is an example of the kind of issue where it’s important to question Rails’ assumptions. We all know Rails is an opinionated framework, whichis often a great thing. But you’re allowed to have opinions too. And when it comes to your user interface, don’t let Rails push you around. Andthere’s a corrollary: URLs are UI. The new routes.rb stuff that David demo’d this morning are great, but I caution you to not unquestioningly followthe Rails-standard path when it comes to your URLs, because it’s quite likely that your URLs will far outlive your implementation -- maybe evenRails itself.

What about reliability?If youre using HTTP methods correctly, reliability is very easy for 3 of the four methods. Remember that GET, PUT, and DELETE are idempotent.When you hear people use that word, you can translate it to "if at ﬁrst you dont succeed, try, try again.". So if you do a PUT and something breaksdown so that you dont get a response, theres no reason not to just re-PUT the request.With POST, its not so simple. What if you POST something and get no response? you can’t know if the POST was received or not, so you cant justtry again, and you cant GET it, because you dont know the new URL.the solution is to break the request into two phases -- ﬁrst PUT [or POST, arguably] to a "resource generator" URL, which will respond with a newURL in the "Location" header, to which the client re-submits the request. If the second request fails, the client can just continue to re-PUT themessage with no worries, or GET it to verify that it worked.

What about concurrency?If you do two PUTs at once, one wins.The solution depends on what you need. For a lot of applications, "last update wins" is a ﬁne strategy. If not, Etags are the solution.

What about transactions?I want to debit one guys account at the same time, and only if, I can credit another guys account. I could do two PUTs in a row, but thats beggingfor inconsistencies to creep into the system.answer 1: YAGNI. Answer 2: what you probably want is a new resource to encapsulate the transaction.

I need more than one representation with the same media type.Can one resource to have two representations of the same type? (eg, an ad-laden HTML view and a printer-friendly HTML view?)Answer 1: I dont know. Answer 2: make a new URI.This is a good reason to think twice before making your "API" media type be application/xml, which is the Rails default. Because what happenswhen you realize that there are actually two XML-based representations that you want to provide for a resource? “application/xml” is about asvague as you can get -- so whenever possible, always try to be more speciﬁc.

How do I handle asynchronous operations, like notifications?answer 1: polling. Answer 2: callbacksGive an app a callback URL for certain events. Blog example. Wishlist example: itd be great if when I entered a new twitter messaage, it wouldPOST it to a URL of my choice, so that I could integrate it with my blog etc., and not have to poll.

There is no API.- I started this talk by pointing out that, whether you know it or not, you have almost certainly built something RESTfully -- because if you ever even put a singlestatic page on the web, its inherently RESTful. So the work becomes recognizing what youre already doing that has been right all along, understanding theprinciples, and then putting those principles into deeper practice.- So I’ll wrap up where we started. You’ll ﬁnd that the closer you move to REST, the less of a distinct API you’ll have at all. The “regular” application and its APIwill become one.- The rub, and it’s a big rub, is not a technical one but a social one. Building on a API requires trust of stability, and “traditional” websites don’t provide for thatexpectation. Hence the need for documentation. Like all human communication, these are problems can’t be completely solved by any formalized system -- italways, eventually boils down to people.

RESTful Web Services Ajax on Rails Unrelat ! ed, New but By Me! sco@scottraymond.netNow, I’ll leave you with a bit of product placement. The book on the left is hot off the presses, by Leonard Richardson and Sam Ruby, and it’s the best singleresource I can recommend to fully understand REST. The second book is mine, and it scarcely touches on REST at all, but I recommend it regardless. :-)Thank you!

Doing REST Right

by Scott Raymond on Sep 30, 2011

Accessibility

Categories

Upload Details

Usage Rights

2 Embeds 16

Statistics

Doing REST Right Document Transcript

http://lanyrd.com	14
http://www.linkedin.com	2