REST – in theory – What makes Internet a success?

View Github Repository Open presentation in a new window

alexm

See all presentation from alexm

REST – in theory – What makes Internet a success?

0 1

rest-in-theory

On Github alexm / rest-in-theory

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:

POST statuses/update Application-user authentication Using OAuth 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!

Questions?

by Alex Muntada / @alexmuntada

REST in peace!