REST

in theory

by Alex Muntada / @alexmuntada

What makes Internet a success?

World Wide Web

What makes the Web a success?

easy
customized
linked
pervasive

Timeline

Architectural Styles and the Design of Network-based Software Architectures

Roy Fielding (2000)

SOAP 1.2

W3C recommendation (2003)

RESTful Web Services

Leonard Richardson, Sam Ruby (2007)

REST becomes a success

RESTful Web APIs

Leonard Richardson, Mike Amundsen, Sam Ruby (2013)

REST(ful)

“Representational state transfer (REST) is a software architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system.”

Architectural Properties of the Web

Low Entry-Barrier (easy)
Extensibility (customized)
Distributed Hypermedia (linked)
Internet-Scale (pervasive)

Interface Constraints

Identification of Resources (URIs)
Manipulation of Resources Through Representations
Self-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 Constraints

Client-Server (one to one)
Statelessness (application state, resource state)
Caching (if-modified-since, if-match, 304)
Uniform Interface
Layered System (proxies, gateways)
Code on Demand (javascript)

APIs

What is your worst nightmare in APIs?

Documentation

Bad, old, wrong or lack thereof.

Twitter REST API v1.1

POST statuses/update

Resource URL: https://api.twitter.com/1.1/statuses/update.json
HTTP Methods: POST
Response Formats: json
Parameters: 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.1
User-Agent: curl/7.35.0
Host: api.twitter.com
Accept: */*
Content-Length: 68
Content-Type: application/x-www-form-urlencoded

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


HTTP/1.1 400 Bad Request
content-length: 61
content-type: application/json; charset=utf-8
date: Sun, 18 May 2014 19:30:43 UTC
server: tfe
set-cookie: guest_id=v1%3A140044144371735781; Domain=.twitter.com; Path=/; Expires=Tue, 17-May-2016 19:30:43 UTC
strict-transport-security: max-age=631138519
x-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.1
User-Agent: curl/7.35.0
Host: api.twitter.com
Accept: */*
Content-Length: 68
Content-Type: application/x-www-form-urlencoded
Authorization:
        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:

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 in different ways, but bridging the gap always requires the intervention of a human being at some point.”

RESTful Web APIs, p. 360

Final Thoughts

Try 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?