REST, l'Architecture Incomprise (PHPTour)

REST est une architecture pour développer des APIs qui repose sur le protocole HTTP combiné à de nombreuses contraintes. Retour sur plus de trois années d'évangélisation avec un bilan mitigé : personne (ou presque) ne comprend vraiment REST, mais ce n'est pas si grave parce qu'il faut savoir être pragmatique et c'est ce que nous verrons !

Online slides: http://slides.williamdurand.fr/nobody-understands-rest/
Sources: https://github.com/willdurand-slides/nobody-understands-rest

Transcript

1. Nobody Understands REST
   but it is ok ;-)
   William Durand - May 12th, 2015
   

   View Slide

2. A Few Words on REST
   

   View Slide

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

   View Slide

4. Richardson Maturity Model
   http://martinfowler.com/articles/richardsonMaturityModel.html
   

   View Slide

5. Levels 0, 1, and 2
   It is all about
   resources
   Client
   uses specific HTTP
   verbs
   Server
   uses HTTP
   status codes
   Content Negotiation
   

   View Slide

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

   View Slide

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

   View Slide

8. Application State
   [null]
   Homepage
   GET /
   User list
   GET /users
   POST /users
   User #123
   GET /users/123
   

   View Slide

9. Resource State
   Initial state
   New state
   Homepage GET /
   User list (2 users) GET /users
   User list (3 users)
   POST
   Homepage GET /
   GET /users
   

   View Slide

10. Resource vs Representation
    A resource can be anything, and can have
    more than one representation.
    A representation describes resource state.
    

    View Slide

11. Protocol Semantics
    How the underlying resource should behave under HTTP?
    

    View Slide

12. Application Semantics
    What specifically will happen to application or resource state?
    

    View Slide

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

    View Slide

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

    View Slide

15. Examples
    Traditional API documentation
    XMDP
    (for
    XHTML
    documents)
    ALPS
    (
    XMDP
    on steroids)
    Embedded doc. (as in
    HAL
    /
    Siren
    )
    JSON-LD
    

    View Slide

16. How To Design A Web API?
    

    View Slide

17. 1. List The Semantic Descriptors
    

    View Slide

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

    View Slide

19. 3. Use Strings From Existing Profiles
    

    View Slide

20. 4. Choose A Media Type
    Don't define your own, please.
    

    View Slide

21. 5. Write A Profile That Documents
    Your Application Semantics
    

    View Slide

22. 6. Eat. Sleep. Code. Repeat.
    

    View Slide

23. 7. Publish The "First" URL
    

    View Slide

24. Mmmmh
    

    View Slide

25. State Of The Art Industry
    

    View Slide

26. We all want RESTful APIs
    

    View Slide

27. Yes.
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

31. Does It Matter?
    

    View Slide

32. Beyond The Constraints
    

    View Slide

33. Often Too Much
    How many
    clients
    do you have?
    Do you know any RESTful client?
    Writing smart clients is complicated
    

    View Slide

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

    View Slide

35. Real Life #2
    , Netflix.
    Pure REST: Slow, hard to program, and rare
    

    View Slide

36. Introducing HTTP++ APIs
    Well-designed, pragmatic, and future-proof APIs.
    

    View Slide

37. Design your API from a client perspective
    

    View Slide

38. Think in terms of representations
    

    View Slide

39. Stick to HTTP
    

    View Slide

40. Still really want to build a RESTful API?
    Choose the
    JSON-LD
    format.
    

    View Slide

41. So What?
    

    View Slide

42. It is ok not to build RESTful APIs
    

    View Slide

43. "REST" is a (marketing) buzzword
    

    View Slide

44. REST is not a silver bullet
    

    View Slide

45. Thank You.
    Questions?
    è joind.in/14276
    ¾ williamdurand.fr
    ® github.com/willdurand
    ¬ twitter.com/couac
    

    View Slide

46. Links
    Hypertext Application Language
    JSON-LD
    Collection+JSON
    Microformats
    XHTML Meta Data Profiles
    Application Language Profile Specification
    Microdata
    Siren
    http://restfulwebapis.com/
    

    View Slide