The Glory of REST

Theory

Source: www.redorbit.com

Web Service

A web service is an abstraction layer, like an operating system API or a programming language library.

RPC-Style Architectures

envelope full of data
HTTP and SOAP are envelope formats
RPC-Style service defines it's own vocabulary
RESTful WS share standard HTTP methods vocabulary
REST Uniform Interface

An RPC-style web service accepts an envelope full of data from its client, and sends a similar envelope back. The method and the scoping information are kept inside the envelope, or on stickers applied to the envelope. What kind of envelope is not important to my classification, but HTTP is a popular envelope format, since any web service worthy of the name must use HTTP anyway. SOAP is another popular envelope format (transmitting a SOAP document over HTTP puts the SOAP envelope inside an HTTP envelope). Every RPC-style service defines a brand new vocabulary. Computer programs work this way as well: every time you write a program, you define functions with different names. By contrast, all RESTful web services share a standard vocabulary of HTTP methods. Every object in a RESTful service responds to the same basic

RESTful - different URIs for different values

RPC-style - URI (service endpoint) for something that can be processed as a command

REST-RPC Hybrid Architectures

Web service between the RESTful web services and the purely RPC-style services

Few REST-RPC examples

The del.icio.us API
The "REST" Flickr web API
Many other allegedly RESTful web services
Most web applications

SOAP as a competitor to REST

The primary competitors to RESTful architectures are RPC architectures, not specific technologies like SOAP.

If you get involved with web service debates you’ll hear this one a lot. You won’t hear it here because it gives the wrong impression. The primary competitors to RESTful architectures are RPC architectures, not specific technologies like SOAP. It is true that basically every SOAP service that now exists has an RPC architecture, but SOAP is just a way of putting a document in an envelope with stickers on it, like HTTP. SOAP is tied to the RPC architecture mainly by historical contingency and the current generation of automated tools. There is a real tension here, but it’s not one I’ll cover much in this book. Roughly speaking, it’s the tension between services that put their documents in a SOAP envelope and then an HTTP envelope; and services that only use the HTTP envelope.

Richardson Maturity Model

Source: http://martinfowler.com

Level 0 - The swamp of POX

HTTP POST for all interactions

Level 1 - Resources

Distinct URL per object

Level 2 - HTTP Verbs

Rather than doing RPC style methods, we leverage HTTP

Level 3 - Hypermedia Controls

Self-describing API

So what is this REST thing?

REST simply dictates that a given resource have a unique address.

You can interact with that address with standard HTTP verbs.

State and Statelessness

Two types of state:

application state - live on the client
resource state - live on the server

Resource state stays on the server and is only sent to the client in the form of representations.

Application state stays on the client until it can be used to create, modify, or delete a resource. Then it's sent to the server as part of POST, PUT, or DELETE request, and becomes resource state.

RESTful service is "stateless" if the server never stores any application state.

This is where the name "Representational State Transfer" comes from.

Etags

ETags are used to compare entities from the same resource. By supplying an entity tag value in a conditional request header.

HTTP provides a simple but powerful mechanism for aligning resource state expectations (and preventing race conditions) in the form of entity tags and conditional request headers. An entity tag value, or ETag, is an opaque string token that a server associates with a resource to uniquely identify the state of the resource over its lifetime. When the resource changes—that is, when one or more of its headers, or its entity body, changes—the entity tag changes accordingly, highlighting that state has been modified. ETags are used to compare entities from the same resource. By supplying an entity tag value in a conditional request header—either an If-Match or an If-None-Match request header—a consumer can require the server to test a precondition related to the current resource state before applying the method supplied in the request.

Resource-Oriented Basics

different audience
everything (interesting) thing represent as a resource
representation of resources
verbs, auxiliaries, complexity

The only differences between a web service and a web site are the audience (preprogrammed clients instead of human beings) and a few client capabilities. Both web services and web sites benefit from a resource-oriented design based on HTTP, URIs, and (usually) XML. Every interesting thing your application manages should be exposed as a resource. A resource can be anything a client might want to link to: a work of art, a piece of information, a physical object, a concept, or a grouping of references to other resources. A URI is the name of a resource. Every resource must have at least one name. A resource should have as few names as possible, and every name should be meaningful. The client cannot access resources directly. A web service serves representations of a resource: documents in specific data formats that contain information about the resource. The difference between a resource and its representation is somewhat academic for static web sites, where the resources are just files on disk that are sent verbatim to clients. The distinction takes on greater importance when the resource is a row in a database, a physical object, an abstract concept, or a real-world event in progress. All access to resources happens through HTTP’s uniform interface. These are the four basic HTTP verbs (GET, POST, PUT, and DELETE), and the two auxiliaries (HEAD and OPTIONS). Put complexity in your representations, in the variety of resources you expose, and in the links between resources. Don’t put it in the access methods.

The Generic ROA Procedure

Figure out the data set
Split the data set into resources

Name the resources with URIs
Expose a subset of the uniform interface
Design the representation(s) accepted from the client
Design the representation(s) served to the client
Integrate this resource into existing resources, using hypermedia links and forms
Consider the typical course of events: what’s supposed to happen? Standard control flows like the Atom Publishing Protocol can help.
Consider error conditions: what might go wrong? Again, standard control flows can help.

Addressability

Representations Should Be Addressable

Let’s say you’ve exposed a press release at /releases/104. There’s an English and a Spanish version of the press release, an HTML and plain-text version of each. Your clients should be able set the Accept-Language request header to choose an English or Spanish representation of /releases/104, and the Accept request header to choose an HTML or plain-text representation. But you should also give each representation a separate URI: maybe URIs like /releases/104.en, /releases/104.es.html, and /releases/104.txt It’s OK for a client to send information in HTTP request headers, so long as the server doesn’t make that the only way of selecting a resource or representation. Headers can also contain sensitive information like authentication credentials, or information that’s different for every client. But headers shouldn’t be the only tool a client has to specify which representation is served or which resource is selected.

Connectedness

Uniform Interface

GET, PUT, and DELETE

POST

HEAD and OPTIONS

Retrieve a metadata-only representation: HTTP HEAD
Check which HTTP methods a particular resource supports: HTTP OPTIONS

PUT versus POST

Overloading POST

The real information may be in the URI, the HTTP headers, or the entity-body. However it happens, an element of the RPC style has crept into the service.

Safety and Idempotence

When correctly used, GET and HEAD requests are safe. GET, HEAD, PUT and DELETE requests are idempotent.

URI Desing

URIs are supposed to designate resources, not operations on the resources.

Method	URI Template	Equivalent RPC Operation
PUT	users/{username}	createUserAccount
GET	users/{username}	getUserAccount
PUT	users/{username}	updateUserAccount
DELETE	users/{username}	deleteUserAccount
GET	users/{username}/profile	getUserProfile
POST	users/{username}/bookmarks	createBookmark
PUT	users/{username}/bookmarks/{id}	updateBookmark
DELETE	users/{username}/bookmarks/{id}	deleteBookmark
GET	users/{username}/bookmarks/{id}	getBookmark
GET	users/{username}/bookmarks?tag={tag}	getUserBookmarks
GET	{username}?tag={tag}	getUserPublicBookmarks
GET	?tag={tag}	getPublicBookmarks

Use commas when the order of the items matters, as it does in latitude and longitude: /earth/37.0,-95.2
Use semicolons when the order doesn’t matter: /color-blends/red;blue
When designing URIs, use path variables to separate elements of a hierarchy, or a path through a directed graph.
Use query variables only to suggest arguments being plugged into an algorithm, or when the other two techniques fail.

Representations

Representations should be human-readable, but computer-oriented

Service Versioning

Even a well-connected service might need to be versioned

Security

HMAC

"Authorization: AWS " + AWSAccessKeyId+ ":" +
                base64(hmac-sha1(VERB + "\n" +
                   CONTENT-MD5 + "\n" +
                   CONTENT-TYPE + "\n" +
                   DATE + "\n" +
                   CanonicalizedAmzHeaders + "\n" +
                   CanonicalizedResource))

Authorization: AWS 44CF9590006BF252F707:jZNOcbfWmD/A/f3hSvVzXZjM2HU=

HMAC allows you to verify the password (or private key) without requiring the user to embed it in the request and also verifies the basic integrity of the request. If an attacker manipulated the request in any way in transit, the signatures would not match and the request would not be authenticated. This is a huge win, especially if the Web service requests are not being made over a secure HTTP connection. In order to calculate the HMAC on the server, I have to remove the incoming HMAC parameter from the request body and calculate the HMAC using the remaining parameters. This is where the previous issue comes into play. If the HMAC were not in the request, I could simply calculate the signature based on the raw incoming request. Once I start manipulating the incoming request, the chances of reconstructing it imperfectly rise, possibly introducing cases where the signatures don’t match even though the request is valid.

JSON or XML

JSON

If all you want to pass around are atomic values or lists or hashes of atomic values, JSON has many of the advantages of XML: it’s straightforwardly usable over the Internet, supports a wide variety of applications, it’s easy to write programs to process JSON, it has few optional features, it’s human-legible and reasonably clear, its design is formal and concise, JSON documents are easy to create, and it uses Unicode.

If you’re writing JavaScript in a web browser, JSON is a natural fit. The XML APIs in the browser are comparitively clumsy and the natural mapping from JavaScript objects to JSON eliminates the serialization issues that arise if you’re careless with XML.

One line of argument for JSON over XML is simplicity. If you mean it’s simpler to have a single data interchange format instead of two, that’s incontrovertibly the case. If you mean JSON is intrinsically simpler than XML, well, I’m not sure that’s so obvious. For bundles of atomic values, it’s a little simpler. And the JavaScript APIs are definitely simpler. But I’ve seen attempts to represent mixed content in JSON and simple they aren’t.

XML

XML deals remarkably well with the full richness of unstructured data. I’m not worried about the future of XML at all even if its death is gleefully celebrated by a cadre of web API designers.

I look forward to seeing what the JSON folks do when they are asked to develop richer APIs. When they want to exchange less well strucured data, will they shoehorn it into JSON? I see occasional mentions of a schema language for JSON, will other languages follow?

I predict there will come a day when someone wants to federate JSON data across several application domains. I wonder, when they discover that the key "width" means different things to different constituencies, will they invent namespaces too?

JSON and Hypermedia

HAL Media Types
HAL and Links
HAL and Resources
HAL Embedded Resources

HAL defines two generic media types: application/hal+xml and application/hal+json. You will use these as the response Content-Type, as they describe the response representation; the client can simply request application/json, and the response format remains compatible. HAL provides a very simple structure for JSON hypermedia links. First, all resource representations must contain hypermedia links, and all links are provided in a “_links” object. HAL imposes no structure over resources other than requiring the hypermedia links; even then, you typically do not include the hypermedia links when making a request of the web service; the hypermedia links are included only in the representations returned by the service. The other important thing that HAL defines is how to embed resources. Why is this important? If the resource references other resources, you will want to be able to link to them so you can perform operations on them, too.

Error handling

Why Status Codes Aren’t Enough?

A status code simply isn’t enough information most of the time. Yes, you want to define standard status codes so that your clients can perform reasonable branching, but you also need a way to communicate details to the end-user, so that they can log the information for themselves, display information to their own end-users, and/or report it back to you so you can do something to resolve the situation.

Sources

THE END

Sławomir Chrobak / @schrobak

Link to presentation: http://schrobak.github.io/slides/tgor