THE GLORY OF REST

THEORY

Source: www.redorbit.com

WEB SERVICEA web service is an abstraction layer, like an

operating system API or a programminglanguage library.

RPC-STYLE ARCHITECTURESenvelope full of dataHTTP and SOAP are envelope formatsRPC-Style service defines it's own vocabularyRESTful WS share standard HTTP methods vocabularyREST Uniform Interface

RESTful - different URIs for different values

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

REST-RPC HYBRID ARCHITECTURESWeb service between the RESTful web

services and the purely RPC-style services

FEW REST-RPC EXAMPLESThe The "REST" Many other allegedly RESTful web servicesMost web applications

del.icio.us APIFlickr web API

SOAP AS A COMPETITOR TO RESTThe primary competitors to RESTful

architectures are RPC architectures, notspecific technologies like SOAP.

RICHARDSON MATURITY MODEL

Source: http://martinfowler.com

LEVEL 0 - THE SWAMP OF POXHTTP POST for all interactions

LEVEL 1 - RESOURCESDistinct URL per object

LEVEL 2 - HTTP VERBSRather than doing RPC style methods, we

leverage HTTP

LEVEL 3 - HYPERMEDIA CONTROLSSelf-describing API

SO WHAT IS THIS RESTTHING?

REST simply dictates that a given resource have a uniqueaddress.

You can interact with that address with standard HTTP verbs.

STATE ANDSTATELESSNESS

TWO TYPES OF STATE:1. application state - live on the client2. resource state - live on the server

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

Application state stays on the client until it can be used tocreate, modify, or delete a resource. Then it's sent to the

server as part of POST, PUT, or DELETE request, andbecomes resource state.

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

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

ETAGSETags are used to compare entities from the

same resource. By supplying an entity tagvalue in a conditional request header.

RESOURCE-ORIENTEDBASICS

different audienceeverything (interesting) thing represent as a resourcerepresentation of resourcesverbs, auxiliaries, complexity

THE GENERIC ROA PROCEDURE1. Figure out the data set

2. Split the data set into resources

For each kind of resource:

3. Name the resources with URIs

4. Expose a subset of the uniform interface

5. Design the representation(s) accepted from the client

6. Design the representation(s) served to the client

7. Integrate this resource into existing resources, using hypermedia links

and forms

8. Consider the typical course of events: what’s supposed to happen?

Standard control flows like the Atom Publishing Protocol can help.

9. Consider error conditions: what might go wrong? Again, standard control

flows can help.

ADDRESSABILITYREPRESENTATIONS SHOULD BE ADDRESSABLE

CONNECTEDNESS

UNIFORM INTERFACE

GET, PUT, AND DELETE

POST

HEAD AND OPTIONSRetrieve a metadata-only representation: HTTP HEADCheck which HTTP methods a particular resourcesupports: HTTP OPTIONS

PUT VERSUS POST

OVERLOADING POSTThe real information may be in the URI, the

HTTP headers, or the entity-body. However ithappens, an element of the RPC style has

crept into the service.

SAFETY ANDIDEMPOTENCEWhen correctly used, GET and HEAD

requests are safe. GET, HEAD, PUT andDELETE requests are idempotent.

URI DESINGURIs are supposed to designate resources, not

operations on the resources.

MethodMethod URI TemplateURI Template Equivalent RPCEquivalent RPCOperationOperation

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 itdoes in latitude and longitude: /earth/37.0,-95.2Use semicolons when the order doesn’t matter: /color-blends/red;blueWhen designing URIs, use path variables to separateelements of a hierarchy, or a path through a directed graph.Use query variables only to suggest arguments beingplugged into an algorithm, or when the other twotechniques fail.

REPRESENTATIONSRepresentations should be human-readable,

but computer-oriented

SERVICE VERSIONINGEven a well-connected service might need to

be versioned

SECURITYHMAC

"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=

JSON OR XML

JSON

If all you want to pass around are atomicvalues or lists or hashes of atomic values,

JSON has many of the advantages of XML: it’sstraightforwardly usable over the Internet,supports a wide variety of applications, it’seasy to write programs to process JSON, it

has few optional features, it’s human-legibleand reasonably clear, its design is formal andconcise, 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 thebrowser are comparitively clumsy and the

natural mapping from JavaScript objects toJSON eliminates the serialization issues that

arise if you’re careless with XML.

One line of argument for JSON over XML issimplicity. If you mean it’s simpler to have a

single data interchange format instead of two,that’s incontrovertibly the case. If you meanJSON 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 theJavaScript APIs are definitely simpler. But I’veseen attempts to represent mixed content in

JSON and simple they aren’t.

XML

XML deals remarkably well with the fullrichness of unstructured data. I’m not worriedabout the future of XML at all even if its death

is gleefully celebrated by a cadre of web APIdesigners.

I look forward to seeing what the JSON folksdo when they are asked to develop richer

APIs. When they want to exchange less wellstrucured data, will they shoehorn it into

JSON? I see occasional mentions of a schemalanguage for JSON, will other languages

follow?

I predict there will come a day when someonewants to federate JSON data across severalapplication domains. I wonder, when they

discover that the key "width" means differentthings to different constituencies, will they

invent namespaces too?

JSON AND HYPERMEDIAHAL Media TypesHAL and LinksHAL and ResourcesHAL Embedded Resources

ERROR HANDLINGWHY STATUS CODES AREN’T ENOUGH?

A status code simply isn’t enough information most of thetime. Yes, you want to define standard status codes so that

your clients can perform reasonable branching, but you alsoneed a way to communicate details to the end-user, so that

they can log the information for themselves, displayinformation to their own end-users, and/or report it back to

you so you can do something to resolve the situation.

SOURCESRESTful Web ServicesMicrosoft REST SpecAmazon's HMAC-SHAHTTP Method DefinitionsJSON and REST presentationHAL Specification

THE ENDSławomir Chrobak /

Link to presentation:

@schrobak

http://schrobak.github.io/slides/tgor