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

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

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.

Dave Ingram

February 25, 2012
Tweet

More Decks by Dave Ingram

Other Decks in Programming

Transcript

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

    View Slide

  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

    View Slide

  3. What this isn’t

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  7. There’s so much more!

    View Slide

  8. URLs

    View Slide

  9. URLs
    verbs

    View Slide

  10. URLs
    verbs
    headers

    View Slide

  11. URLs
    verbs
    headers
    authentication

    View Slide

  12. URLs
    verbs
    headers
    authentication
    formats

    View Slide

  13. URLs
    verbs
    headers
    authentication
    formats
    validty

    View Slide

  14. URLs
    verbs
    headers
    authentication
    formats
    validty
    documentation

    View Slide

  15. DOCUMENTATION

    View Slide

  16. DOCUMENTATION
    (later)

    View Slide

  17. Part 1: URLs

    View Slide

  18. Make them
    versioned

    View Slide

  19. Make them
    versioned,
    hackable

    View Slide

  20. Make them
    versioned,
    hackable &
    meaningful

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  25. Look at URLs from a
    consumer perspective

    View Slide

  26. They don’t care about internal
    implementation details

    View Slide

  27. Use common sense

    View Slide

  28. A good routing system is your
    friend
    You don’t want to be issuing 3xx redirects
    because consumers forgot a slash

    View Slide

  29. Part 2: Verbs

    View Slide

  30. (in terms of model operations)

    View Slide

  31. • GET = get()
    • PUT = set() / new Obj($id)
    • POST = new Obj() / doThing()
    • DELETE = delete()
    • HEAD ≈ getMetadata()
    • OPTIONS ≈ Reflection

    View Slide

  32. Must at least support GET/POST

    View Slide

  33. Can emulate PUT/DELETE

    View Slide

  34. HEAD is rare and can probably
    be ignored

    View Slide

  35. OPTIONS is used by CORS, but
    otherwise rare

    View Slide

  36. Part 3: Headers

    View Slide

  37. Headers are important too!

    View Slide

  38. Some headers let you be clever

    View Slide

  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.

    View Slide

  40. Some headers reduce traffic
    (important for mobile)

    View Slide

  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?

    View Slide

  42. Part 4: Authentication &
    Authorization

    View Slide

  43. OAuth2 over HTTPS

    View Slide

  44. OAuth2 over HTTPS
    (that’s it)

    View Slide

  45. Much simpler than OAuth 1.0

    View Slide

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

    View Slide

  47. Part 5: Formats

    View Slide

  48. Sane default: JSON, plus
    envelope with metadata

    View Slide

  49. {
    "meta": {
    "code": 200,
    "dev_notes": [
    "This endpoint is deprecated"
    ]
    },
    "response": {
    ...
    }
    }

    View Slide

  50. Use XML if you must,
    or if users really want it

    View Slide

  51. Idealistic REST XML is verbose
    and people may hate you
    (unless they’re building an API explorer)

    View Slide

  52. Don’t forget: mobile bandwidth
    is still very limited

    View Slide

  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.

    View Slide

  54. Part 6: Validity

    View Slide

  55. Allow your consumers to cache
    data wherever possible

    View Slide

  56. Encourage use of request headers:
    • GET:
    • If-Modified-Since
    • If-None-Match
    • POST/PUT/DELETE:
    • If-Unmodified-Since
    • If-Match

    View Slide

  57. Return useful response headers:
    • Last-Modified
    • Expires
    • ETag
    • Cache-Control

    View Slide

  58. Deal with preconditions and give
    appropriate response codes

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  64. Part 7: Documentation

    View Slide

  65. Documentation is important

    View Slide

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

    View Slide

  67. Use examples liberally. . .
    and make sure they’re both
    up-to-date and correct!

    View Slide

  68. Assume nothing;
    explain everything

    View Slide

  69. Try building something using
    only your own API docs

    View Slide

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

    View Slide