Slide 1
Slide 1 text
Nobody Understands REST
but it is ok ;-)
William Durand - May 12th, 2015
Slide 2
Slide 2 text
A Few Words on REST
Slide 3
Slide 3 text
REpresentational State Transfer
REST is the underlying architectural principle of the web.
It is formalized as a set of constraints, described in
Roy Fielding's PhD dissertation.
Slide 4
Slide 4 text
Richardson Maturity Model
http://martinfowler.com/articles/richardsonMaturityModel.html
Slide 5
Slide 5 text
Levels 0, 1, and 2
It is all about
resources
Client
uses specific HTTP
verbs
Server
uses HTTP
status codes
Content Negotiation
Slide 6
Slide 6 text
Level 3 - Hypermedia Controls
Service discovery via
relations
Hypermedia
formats (e.g. HTML, HAL, JSON-LD)
Resources are not important, their
representations
are!
URI design does
not
matter (URI template)
Client's experience
is crucial!
Protocol &
application semantics
Slide 7
Slide 7 text
HATEOAS
Hypermedia As The Engine Of Application State
It means that hypermedia should be used to find your
way through the API. It is all about state transitions.
Your application is just a big state machine.
Slide 8
Slide 8 text
Application State
[null]
Homepage
GET /
User list
GET /users
POST /users
User #123
GET /users/123
Slide 9
Slide 9 text
Resource State
Initial state
New state
Homepage GET /
User list (2 users) GET /users
User list (3 users)
POST
Homepage GET /
GET /users
Slide 10
Slide 10 text
Resource vs Representation
A resource can be anything, and can have
more than one representation.
A representation describes resource state.
Slide 11
Slide 11 text
Protocol Semantics
How the underlying resource should behave under HTTP?
Slide 12
Slide 12 text
Application Semantics
What specifically will happen to application or resource state?
Slide 13
Slide 13 text
The Semantic Challenge*
Some standards have a good protocol-level semantics
but no application-level semantics (
Collection+JSON
,
Atom
).
Some standards define a lot of application-level semantics
but no protocol semantics (
Microformats
,
Microdata
).
* as described in Richardson and Amundsen's "RESTful Web APIs" book
Slide 14
Slide 14 text
Profiles
A profile is defined to not alter the semantics of the
resource representation itself, but to allow clients to
learn about additional semantics, .
It does not have to be machine-readable but it is recommended.
RFC 6906
Slide 15
Slide 15 text
Examples
Traditional API documentation
XMDP
(for
XHTML
documents)
ALPS
(
XMDP
on steroids)
Embedded doc. (as in
HAL
/
Siren
)
JSON-LD
Slide 16
Slide 16 text
How To Design A Web API?
Slide 17
Slide 17 text
1. List The Semantic Descriptors
Slide 18
Slide 18 text
2. Draw A State Diagram
Each "box" represents one kind of representation
Arrows are the
state transitions
(HTTP requests)
Change descriptors to relations when it makes sense
Slide 19
Slide 19 text
3. Use Strings From Existing Profiles
Slide 20
Slide 20 text
4. Choose A Media Type
Don't define your own, please.
Slide 21
Slide 21 text
5. Write A Profile That Documents
Your Application Semantics
Slide 22
Slide 22 text
6. Eat. Sleep. Code. Repeat.
Slide 23
Slide 23 text
7. Publish The "First" URL
Slide 24
Slide 24 text
Mmmmh
Slide 25
Slide 25 text
State Of The Art Industry
Slide 26
Slide 26 text
We all want RESTful APIs
Slide 27
Slide 27 text
Yes.
Slide 28
Slide 28 text
Is My API RESTful When I Use JSON?
, The REST CookBook.
Short answer: no. Long answer: no, not yet.
RESTful API must use hypermedia formats. JSON is
not a hypermedia format
Slide 29
Slide 29 text
s/REST/HTTP++/
REST APIs are a myth, i.e. too complex in real life.
, Steve Klabnik
.
99.99% of the RESTful APIs out there aren’t fully compliant
with Roy Fielding’s conception of REST
Slide 30
Slide 30 text
No Relations = No REST
, Roy Fielding.
If the engine of application state (and hence the API)
is not being driven by hypertext, then it cannot be
RESTful and cannot be a REST API
Slide 31
Slide 31 text
Does It Matter?
Slide 32
Slide 32 text
Beyond The Constraints
Slide 33
Slide 33 text
Often Too Much
How many
clients
do you have?
Do you know any RESTful client?
Writing smart clients is complicated
Slide 34
Slide 34 text
Real Life #1
, Facebook (on Relay/GraphQL).
Because of multiple round-trips and over-fetching,
applications built in the REST style end up building
ad hoc endpoints
Slide 35
Slide 35 text
Real Life #2
, Netflix.
Pure REST: Slow, hard to program, and rare
Slide 36
Slide 36 text
Introducing HTTP++ APIs
Well-designed, pragmatic, and future-proof APIs.
Slide 37
Slide 37 text
Design your API from a client perspective
Slide 38
Slide 38 text
Think in terms of representations
Slide 39
Slide 39 text
Stick to HTTP
Slide 40
Slide 40 text
Still really want to build a RESTful API?
Choose the
JSON-LD
format.
Slide 41
Slide 41 text
So What?
Slide 42
Slide 42 text
It is ok not to build RESTful APIs
Slide 43
Slide 43 text
"REST" is a (marketing) buzzword
Slide 44
Slide 44 text
REST is not a silver bullet
Slide 45
Slide 45 text
Thank You.
Questions?
è joind.in/14276
¾ williamdurand.fr
® github.com/willdurand
¬ twitter.com/couac
Slide 46
Slide 46 text
Links
Hypertext Application Language
JSON-LD
Collection+JSON
Microformats
XHTML Meta Data Profiles
Application Language Profile Specification
Microdata
Siren
http://restfulwebapis.com/