in theory

by Alex Muntada / @alexmuntada

What makes Internet a success?

World Wide Web

What makes the Web a success?

  • easy
  • customized
  • linked
  • pervasive


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)

RWA cover

REST becomes a success

RWSC cover RP cover RADR cover

RESTful Web APIs

Leonard Richardson, Mike Amundsen, Sam Ruby (2013)

RWS cover


“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)


“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)


De professió: API De professió: API De professió: API

What is your worst nightmare in APIs?


Bad, old, wrong or lack thereof.

Twitter REST API v1.1

POST statuses/update

  • Resource URL:
  • 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
Accept: */*
Content-Length: 68
Content-Type: application/x-www-form-urlencoded


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;; 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
Accept: */*
Content-Length: 68
Content-Type: application/x-www-form-urlencoded
        OAuth oauth_consumer_key="xvz1evFS4wEEPTGEFPHBog",


How did I find that?

Read several pages of documentation:

  1. POST statuses/update
  2. Application-user authentication
  3. Using OAuth
  4. Authorizing 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 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!


by Alex Muntada / @alexmuntada

REST in peace!