The document discusses the principles and architectural constraints of REST (Representational State Transfer) and its significance in web APIs, emphasizing the importance of ease of use, extensibility, and stateless communication. It critiques common problems in API documentation and suggests utilizing hypermedia and existing standards to enhance usability. The author encourages API designers to consider the semantic aspects of their design to bridge the gap between document structure and real-world semantics.

1. REST
in theory
by Alex Muntada / @alexmuntada

2. What makes Internet a success?
World Wide Web

3. What makes the Web a success?
easy
customized
linked
pervasive

4. Timeline

5. Architectural Styles and the
Design of Network-based
Software Architectures
Roy Fielding (2000)

6. SOAP 1.2
W3C recommendation (2003)

7. RESTful Web Services
Leonard Richardson, Sam Ruby (2007)

8. REST becomes a success

9. RESTful Web APIs
Leonard Richardson, Mike Amundsen, Sam Ruby (2013)

10. 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.”

11. Architectural Properties of the Web
Low Entry-Barrier (easy)
Extensibility (customized)
Distributed Hypermedia (linked)
Internet-Scale (pervasive)

12. Interface Constraints
Identification of Resources (URIs)
Manipulation of Resources Through Representations
Self-Descriptive Messages (stateless)
The Hypermedia Constraint (HATEOAS)

13. 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.

14. 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)

15. APIs

16. What is your worst nightmare in APIs?
Documentation
Bad, old, wrong or lack thereof.

17. 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

18. 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 strict-transport-security: max-age=631138519
x-tfe-logging-request-category: API
{"errors":[{"message":"Bad Authentication data","code":215}]}

19. 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

20. 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

21. 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

22. 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!

23. Questions?
by Alex Muntada / @alexmuntada

24. REST in peace!