API Design: More Than the REST (PHPUK 2012 uncon)

15c49bd9f73317bf66952b9ee17414ef?s=47 Dave Ingram
February 25, 2012

API Design: More Than the REST (PHPUK 2012 uncon)

We've all heard a lot about REST APIs. But REST is not everything; there is so much more!

This was a short talk given at the PHPUK 2012 unconference.

15c49bd9f73317bf66952b9ee17414ef?s=128

Dave Ingram

February 25, 2012
Tweet

Transcript

  1. API design More than the REST Dave Ingram @dmi February

    25, 2012
  2. Who am I? • Coder and Release Manager at GroupSpaces

    • Twitter: @dmi • Github: dingram • Also occasionally found at London Hackspace • Feedback: http://joind.in/6137
  3. What this isn’t

  4. ST ST T T REST REST REST REST REST REST

    REST REST EST EST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST EST REST REST REST REST REST REST REST REST REST RE REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST T REST REST REST REST REST REST REST REST REST REST RE RES RES RES REST REST REST REST REST REST R R R RE
  5. ST ST T T REST REST REST REST REST REST

    REST REST EST EST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST EST REST REST REST REST REST REST REST REST REST RE REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST T REST REST REST REST REST REST REST REST REST REST RE RES RES RES REST REST REST REST REST REST R R R RE
  6. ST ST T T REST REST REST REST REST REST

    REST REST EST EST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST EST REST REST REST REST REST REST REST REST REST RE REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST T REST REST REST REST REST REST REST REST REST REST RE RES RES RES REST REST REST REST REST REST R R R RE
  7. There’s so much more!

  8. URLs

  9. URLs verbs

  10. URLs verbs headers

  11. URLs verbs headers authentication

  12. URLs verbs headers authentication formats

  13. URLs verbs headers authentication formats validty

  14. URLs verbs headers authentication formats validty documentation

  15. DOCUMENTATION

  16. DOCUMENTATION (later)

  17. Part 1: URLs

  18. Make them versioned

  19. Make them versioned, hackable

  20. Make them versioned, hackable & meaningful

  21. http://api.com/v1/

  22. http://api.com/v1/users/

  23. http://api.com/v1/users/31337

  24. http://api.com/v1/users/31337/posts/

  25. Look at URLs from a consumer perspective

  26. They don’t care about internal implementation details

  27. Use common sense

  28. A good routing system is your friend You don’t want

    to be issuing 3xx redirects because consumers forgot a slash
  29. Part 2: Verbs

  30. (in terms of model operations)

  31. • GET = get() • PUT = set() / new

    Obj($id) • POST = new Obj() / doThing() • DELETE = delete() • HEAD ≈ getMetadata() • OPTIONS ≈ Reflection
  32. Must at least support GET/POST

  33. Can emulate PUT/DELETE

  34. HEAD is rare and can probably be ignored

  35. OPTIONS is used by CORS, but otherwise rare

  36. Part 3: Headers

  37. Headers are important too!

  38. Some headers let you be clever

  39. Accept The MIME types the client will accept. No need

    to use file extensions to decide what content type to serve! Accept-Language The languages the client will accept. No need to ask clients or (worse) just assume English responses.
  40. Some headers reduce traffic (important for mobile)

  41. • ETag – A unique tag for the content •

    If-(None-)Match – Check ETag • If-Modified-Since – Cached by client • Cache-Control – Can it be cached?
  42. Part 4: Authentication & Authorization

  43. OAuth2 over HTTPS

  44. OAuth2 over HTTPS (that’s it)

  45. Much simpler than OAuth 1.0

  46. Many libraries for OAuth2, as it’s a popular standard

  47. Part 5: Formats

  48. Sane default: JSON, plus envelope with metadata

  49. { "meta": { "code": 200, "dev_notes": [ "This endpoint is

    deprecated" ] }, "response": { ... } }
  50. Use XML if you must, or if users really want

    it
  51. Idealistic REST XML is verbose and people may hate you

    (unless they’re building an API explorer)
  52. Don’t forget: mobile bandwidth is still very limited

  53. Timestamps • ISO-8601 2012-02-25T14:00:00Z Human-readable(ish), but needs parsing • UTC

    seconds since epoch: 1330178400 Easily machine-usable Should your API really be human-readable? It’s better to help your consumers.
  54. Part 6: Validity

  55. Allow your consumers to cache data wherever possible

  56. Encourage use of request headers: • GET: • If-Modified-Since •

    If-None-Match • POST/PUT/DELETE: • If-Unmodified-Since • If-Match
  57. Return useful response headers: • Last-Modified • Expires • ETag

    • Cache-Control
  58. Deal with preconditions and give appropriate response codes

  59. For example: ETag and Last-Modified can help prevent race conditions

  60. PUT /wiki/dealing-with-conflicts HTTP/1.1 Host: api.com If-Unmodified-Since: Sat, 18 Feb 2012

    11:09:21 GMT If-Match: "x-rev-11294" Content-Type: text/html ... 412 Precondition Failed ETag: "x-rev-11467" Last-Modified: Sat, 25 Feb 2012 14:42:53 GMT ...
  61. PUT /wiki/dealing-with-conflicts HTTP/1.1 Host: api.com If-Unmodified-Since: Sat, 18 Feb 2012

    11:09:21 GMT If-Match: "x-rev-11294" Content-Type: text/html ... 412 Precondition Failed ETag: "x-rev-11467" Last-Modified: Sat, 25 Feb 2012 14:42:53 GMT ...
  62. PUT /wiki/dealing-with-conflicts HTTP/1.1 Host: api.com If-Unmodified-Since: Sat, 18 Feb 2012

    11:09:21 GMT If-Match: "x-rev-11294" Content-Type: text/html ... 412 Precondition Failed ETag: "x-rev-11467" Last-Modified: Sat, 25 Feb 2012 14:42:53 GMT ...
  63. PUT /wiki/dealing-with-conflicts HTTP/1.1 Host: api.com If-Unmodified-Since: Sat, 18 Feb 2012

    11:09:21 GMT If-Match: "x-rev-11294" Content-Type: text/html ... 412 Precondition Failed ETag: "x-rev-11467" Last-Modified: Sat, 25 Feb 2012 14:42:53 GMT ...
  64. Part 7: Documentation

  65. Documentation is important

  66. If people can’t understand your API, they won’t use it

  67. Use examples liberally. . . and make sure they’re both

    up-to-date and correct!
  68. Assume nothing; explain everything

  69. Try building something using only your own API docs

  70. Thanks! http://dmi.me.uk/talks/ http://joind.in/6137 Built in L ATEX Inspired by: http://goo.gl/0mT55