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

REST API's: What I Wish Someone Had Told Me

weaverryan
October 30, 2014

REST API's: What I Wish Someone Had Told Me

Make no mistake, creating a "RESTful" API is hard work. It's packed full of theory and is's notorious for being difficult to find the fine line between getting it done and doing it "correctly". In this talk, we'll start through the must-know basics, like HTTP methods, status codes, resources and representations. But then, we'll turn to the harder stuff: hypermedia, links, hypermedia formats: what to worry about and what to leave behind. We'll also talk about error representations, serialization, custom methods (e.g. "buy" a book) and documentation for all of this (machine docs and human docs). In short, I'll show you what I wish I had always known: what pieces of REST to leave behind and some strategies on how to tackle the tough stuff that you *do* need.

weaverryan

October 30, 2014
Tweet

More Decks by weaverryan

Other Decks in Technology

Transcript

  1. KnpUniversity.com github.com/weaverryan Who is this Hipster? > Lead for the

    Symfony documentation
 > KnpLabs US - Symfony Consulting, training, Kumbaya ! > Writer for KnpUniversity.com Tutorials > Husband of the much more talented @leannapelham
  2. @weaverryan GET /api/programmers/5 HTTP 1.1! Host: CodeBattles.io! Accept: application/json,text/html HTTP/1.1

    200 OK! Content-Type: application/json! ! {! "id": 5,! "nickname": "Namespacinator"! }
  3. @weaverryan Documentation Resources Hypermedia HATEOAS Testing Representations Resource State $MJFOU4UBUF

    Status Codes Links Embedded Resources Content-Negotation Location Header Idempotency PUT, POST, PATCH Pagination Filtering
  4. > design your API ! > play with it !

    > implement ! > use your design as a test @weaverryan
  5. If you build it with no (or incorrect) docs… !

    people can’t use it womp womp @weaverryan
  6. POST /api/programmers HTTP/1.1! Host: CodeBattles.io! Content-type: application/json! Accept: application/json,text/html! !

    {! "nickname": "ObjectOrienter",! "avatarNumber" : "2",! "tagLine": "Testing!"! } @weaverryan
  7. HTTP/1.1 201 Created! Content-type: application/json! Location: /api/programmers/2! ! {! "id":

    2,! "nickname": "ObjectOrienter",! "avatarNumber" : "2",! "tagLine": "Testing!"! } @weaverryan
  8. REST == 1) A system where a client can change

    the data of 
 a resource ! ! 2) The server can respond with the data of a resource @weaverryan
  9. Server: ! impacts client state by sending links that suggest

    what to do next (like an HTML page) @weaverryan
  10. TIP! Hypermedia: ! it’s just JSON/XML with links … and

    sends back a special content-type header to tell the user about your format @weaverryan
  11. but don’t expect your API client to become self-aware and

    learn your API entirely by links… yet @weaverryan
  12. New Programer Response @weaverryan {! "_links": {! "self": {! "href":

    "http://example.org/ }! },! "id": "2",! "nickname": "ObjectOrienter",! "tagLine": "Testing!"! }!
  13. Chapter 4 ! It doesn’t have to be good It

    has to be consistent @weaverryan
  14. Serialization includes everything: ! > Links > Embedded Resources >

    Pagination** > Filters** > Hypermedia Formatting ** BTW, use query parameters for pagination and filtering
  15. @weaverryan HTTP/1.1 400 Bad Request Content-Type: application/problem+json ! { "errors":

    {"nickname":"Enter a clever nickname"}, "status":400, "type": " http://example.com /docs/errors#validation_error”, "title":"There was a validation error” }
  16. TIP! Be consistent, but simple, with status codes 200: most

    response 201: after creating a resource 204: a 200, but blank response (e.g. delete resource) 400: validation errors or bad data format 401/403: Unauthorized/Access Denied 500: things are not good 202: If the resource will be created later 422: Could be used for validation errors
  17. TIP! Don’t get obsessed with *accepting* multiple input formats !

    “we support sending json, XML or www- form-urlencoded data!” @weaverryan Why?
  18. TIP! Use OAuth? Or maybe a simple token-based authentication …

    sure, if you have bigger requirement, use something bigger @weaverryan
  19. Idempotency: ! Is it guaranteed to be safe if I

    accidentally make a request twice in a row? @weaverryan
  20. TIP! PUT if *both* of the following are true: 1)

    The request is idempotent ! 2) The URI is to the resource being updated … otherwise, use POST
  21. @weaverryan /api/programmers POST Not Idempotent /api/programers/5 PUT /api/programmers/5/avatar PUT /api/programmers/5/sleep

    POST URI is not to resource being updated POST != idempotent, but making a request twice doesn’t *need* to have a side-effect
  22. TIP! > Use either PATCH or PUT
 ! > Ignore

    how they’re supposed to work
 ! > Document clearly how you’re using them @weaverryan
  23. 6) Use PUT if it follows the 2 rules, POST

    as the catch-all @weaverryan
  24. Thanks! Ryan Weaver @weaverryan KnpUniversity.com PHP , Behat, Twig, OO,

    etc Tutorial Screencasts https://joind.in/12084