REST, l'Architecture Incomprise (PHPTour)

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

F59d2f1ed66b8d9c6ceebea5a748494b?s=128

William Durand

May 12, 2015
Tweet

Transcript

  1. 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.
  2. 5.

    Levels 0, 1, and 2 It is all about resources

    Client uses specific HTTP verbs Server uses HTTP status codes Content Negotiation
  3. 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
  4. 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.
  5. 8.
  6. 9.

    Resource State Initial state New state Homepage GET / User

    list (2 users) GET /users User list (3 users) POST Homepage GET / GET /users
  7. 10.

    Resource vs Representation A resource can be anything, and can

    have more than one representation. A representation describes resource state.
  8. 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
  9. 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
  10. 15.

    Examples Traditional API documentation XMDP (for XHTML documents) ALPS (

    XMDP on steroids) Embedded doc. (as in HAL / Siren ) JSON-LD
  11. 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
  12. 24.
  13. 27.
  14. 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
  15. 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
  16. 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
  17. 33.

    Often Too Much How many clients do you have? Do

    you know any RESTful client? Writing smart clients is complicated
  18. 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
  19. 41.
  20. 46.

    Links Hypertext Application Language JSON-LD Collection+JSON Microformats XHTML Meta Data

    Profiles Application Language Profile Specification Microdata Siren http://restfulwebapis.com/