RESTin theory

by / Alex Muntada @alexmuntada

What makes Internet a success?

World Wide Web

What makes the Web a success?easycustomizedlinkedpervasive

Timeline

Architectural Styles and theDesign of Network-based

Software ArchitecturesRoy Fielding (2000)

SOAP 1.2W3C recommendation (2003)

RESTful Web ServicesLeonard Richardson, Sam Ruby (2007)

REST becomes a success

RESTful Web APIsLeonard Richardson, Mike Amundsen, Sam Ruby (2013)

REST(ful)“Representational state transfer (REST) is a softwarearchitectural style consisting of a coordinated set ofarchitectural constraints applied to components,connectors, and data elements, within a distributed

hypermedia system.”

Architectural Properties of the WebLow Entry-Barrier (easy)Extensibility (customized)Distributed Hypermedia (linked)Internet-Scale (pervasive)

Interface ConstraintsIdentification of Resources (URIs)Manipulation of Resources Through RepresentationsSelf-Descriptive Messages (stateless)The Hypermedia Constraint (HATEOAS)

HATEOAS“Hypermedia as the engine of application state.”

All application state is kept on the client side.The client can only change it through HTTP requests and responses.The client can find next actions through hypermedia controls.Hypermedia controls drive changes in application state.

Architectural ConstraintsClient-Server (one to one)Statelessness (application state, resource state)Caching (if-modified-since, if-match, 304)

Layered System (proxies, gateways)Code on Demand (javascript)

Uniform Interface

APIs

What is your worst nightmare in APIs?

DocumentationBad, old, wrong or lack thereof.

Twitter REST API v1.1POST statuses/update

Resource URL: https://api.twitter.com/1.1/statuses/update.jsonHTTP Methods: POSTResponse Formats: jsonParameters: status (required), in_reply_to_status_id, lat, long, place_id,display_coordinates, trim_user

What is missing in this example?POST /1.1/statuses/update.json HTTP/1.1User-Agent: curl/7.35.0Host: api.twitter.comAccept: */*Content-Length: 68Content-Type: application/x-www-form-urlencoded

status=Maybe%20he%27ll%20finally%20find%20his%20keys.%20%23peterfalk

HTTP/1.1 400 Bad Requestcontent-length: 61content-type: application/json; charset=utf-8date: Sun, 18 May 2014 19:30:43 UTCserver: tfeset-cookie: guest_id=v1%3A140044144371735781; Domain=.twitter.com; Path=/; Expires=Tue, 17-May-2016 19:30:43 UTCstrict-transport-security: max-age=631138519x-tfe-logging-request-category: API

{"errors":[{"message":"Bad Authentication data","code":215}]}

How can I fix it?POST /1.1/statuses/update.json HTTP/1.1User-Agent: curl/7.35.0Host: api.twitter.comAccept: */*Content-Length: 68Content-Type: application/x-www-form-urlencodedAuthorization: OAuth oauth_consumer_key="xvz1evFS4wEEPTGEFPHBog", oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg", oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1318622958", oauth_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb", oauth_version="1.0"

status=Maybe%20he%27ll%20finally%20find%20his%20keys.%20%23peterfalk

How did I find that?Read several pages of documentation:1. 2. 3. 4.

POST statuses/updateApplication-user authenticationUsing OAuthAuthorizing a request

The Semantic Gap“The gap between the structure of a document and its

real-world meaning—its application semantics.Media types, machine-readable profiles, and human-readable documentation bridge the semantic gap indifferent ways, but bridging the gap always requiresthe intervention of a human being at some point.”

RESTful Web APIs, p. 360

Final ThoughtsTry to use less documentation and more hypermedia.Use existing standards, content types, link relations, etc.Propose new ones when there are none.Think about Internet-scale APIs.Let your APIs socialize with other APIs.Embrace the semantic challenge!

Questions?by Alex Muntada / @alexmuntada

REST in peace!