Upgrade to Pro — share decks privately, control downloads, hide ads and more …

REST: from zero to hero

REST: from zero to hero

[FR]
Venez découvrir - ou redécouvrir ! - les différents ingrédients qui sont a l’origine d’une bonne API.

Nous présenterons la transformation d’une API Web fictive (d'une conception assez discutable ;-) ) en une API REST vraiment user-friendly. Chaque étape sera l’occasion d’introduire un concept ou une bonne pratique supplémentaire en partant des bases de REST jusqu’aux sujets avancés tels que le versioning ou l’hypermédia.

Vous sortirez de cette session avec une vision claire des concepts cachés derrière le terme "REST".

0d67d4ac82fb031ff815245ae00e1a97?s=128

Antoine RICHARD

November 06, 2015
Tweet

Transcript

  1. REST from zero to hero in 45 minutes

  2. Manuel Boillod Code Artist @mboillod Antoine Richard Code Rider @richard_antoine

  3. None
  4. GET /api/listSpeaker GET /api/displaySpeaker?id=34 POST /api/updateSpeaker?id=34 POST /api/addSpeaker GET /api/deleteSpeaker?id=34

  5. HTTP AS A TUNNEL

  6. HTTP AS A TOOLBOX

  7. None
  8. RESOURCES & VERBS

  9. A network data object or service that can be identified

    by a URI, as defined in section 3.2. Resources may be available in multiple representations (e. g. multiple languages, data formats, size, and resolutions) or vary in other ways. RFC 2616 (june 1999)
  10. A resource is anything that’s important enough to be referenced

    as a thing in itself Leonard Richardson & Sam Ruby
  11. 5.1.1 Method The Method token indicates the method to be

    performed on the resource identified by the Request-URI. The method is case- sensitive. Method = "OPTIONS" ; Section 9.2 | "GET" ; Section 9.3 | "HEAD" ; Section 9.4 | "POST" ; Section 9.5 | "PUT" ; Section 9.6 | "DELETE" ; Section 9.7 | “PATCH” ; RFC 5789 (2010) RFC 2616 (june 1999)
  12. /api/speakers - GET - POST /api/speakers/{id} - GET - PUT

    - PATCH - DELETE
  13. None
  14. POST /api/noteSession?session=12&note=4 POST /api/sessions/{id}/notes/4

  15. # Sub-resources POST /api/sessions/{id}/notes {"value": 4} GET /api/sessions/{id}/notes [ {

    "session": "s21", "value": 4 }, … ]
  16. # Resources GET /api/notes POST /api/notes {"session": "s25", "value": 5}

    GET /api/notes/{id}
  17. # Resource GET /api/stats/notes?session=s2 { "avg": 3.4, "count": 6, "max":

    5, "min": 1, "session": "s2" }
  18. # Actions POST /api/stats/notes { "by": "session"} [ { "avg":

    3.4, "count": 6, "max": 5, "min": 1, "session": "s2" }, … ]
  19. STATUS CODES

  20. 1xx Hold on 2xx Here you go 3xx Go away

    4xx You f**ked up 5xx I f**ked up
  21. None
  22. None
  23. “The action performed by the POST method might not result

    in a resource that can be identified by a URI. In this case, either 200 (OK) or 204 (No Content) is the appropriate response status, depending on whether or not the response includes an entity that describes the result. If a resource has been created on the origin server, the response SHOULD be 201 (Created) and contain an entity which describes the status of the request and refers to the new resource, and a Location header.” http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5
  24. HAPI.JS

  25. > POST /speakers {...} HTTP/1.1 201 Created Location: /speakers/spiderman {

    "id": "spiderman", "firstname": "peter", "lastname": "parker" }
  26. PAGINATION

  27. • Using page number (or equivalent) ◦ No deterministic with

    insertion GET api/sessions?page=4&sort=hour GET api/sessions?after=s20&sort=hour • Comparing on element id ◦ Easy navigation to previous and next ◦ Impossible to go directly to middle
  28. 200 OK 206 Partial Content

  29. > GET /speakers?page=4 HTTP/1.1 206 Partial Content Link: </speakers?page=1>; rel="first",

    </speakers?page=3>; rel="prev", </speakers?page=5>; rel="next", </speakers?page=9>; rel="last" { "items": [{ "id": "spiderman" }, … ], "count": 25, "total": 237 }
  30. DOCUMENTATION

  31. None
  32. CONTENT NEGOTIATION

  33. > GET /sessions/s12 HTTP/1.1 Accept: application/json HTTP/1.1 200 OK Content-Type:

    application/json { "id": "s12", "title": "OMG! Terminator sera codé en Javascript!" }
  34. > GET /sessions/s12 HTTP/1.1 Accept: application/xml HTTP/1.1 406 Not Acceptable

  35. Accept: application/x-yaml, text/yaml, application/json;q=0.9, */*;q=0.8 Accept-Charset: utf-8, iso-8859-1;q=0.8 Accept-Encoding: gzip

    Accept-Language: en-US, en;q=0.8, fr;q=0.6
  36. None
  37. HYPERMEDIA

  38. HAL Collection+JSON JSON-API Siren Hydra NARWHL UBER Mason JSON-LD

  39. H A L

  40. DHC: a REST/HTTP API Client restlet.com/products/dhc

  41. HATEOAS

  42. None
  43. A REST API should be entered with no prior knowledge

    beyond the initial URI and set of standardized media types that are appropriate for the intended audience. From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The Glory of REST by Roy Fielding
  44. None
  45. VERSIONING

  46. URI

  47. https://devfest.gdgnantes.com/api/v2/speakers

  48. URI Accept Header

  49. Accept: application/vnd.speakers.v2+json

  50. URI Accept Header Hypermedia

  51. None
  52. None
  53. REST SUPERHEROES

  54. github.com/boillodmanuel/rest-from-zero-to-hero @richard_antoine @mboillod speakerdeck.com/antoinerichard/rest-from-zero-to-hero