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

API Design: It's Not Rocket Surgery

API Design: It's Not Rocket Surgery

Designing an API well shouldn't be difficult. In this talk, I'll take a look at some of the things that you should consider in order to play well with others.

Dave Ingram

May 03, 2012
Tweet

More Decks by Dave Ingram

Other Decks in Technology

Transcript

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

    View full-size 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 full-size slide

  3. What this isn’t

    View full-size 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 full-size 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 full-size 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 full-size slide

  7. There’s so much more!

    View full-size slide

  8. URLs
    verbs
    headers

    View full-size slide

  9. URLs
    verbs
    headers
    authentication

    View full-size slide

  10. URLs
    verbs
    headers
    authentication
    formats

    View full-size slide

  11. URLs
    verbs
    headers
    authentication
    formats
    validty

    View full-size slide

  12. URLs
    verbs
    headers
    authentication
    formats
    validty
    documentation

    View full-size slide

  13. DOCUMENTATION

    View full-size slide

  14. DOCUMENTATION
    (later)

    View full-size slide

  15. Part 1: URLs

    View full-size slide

  16. Make them
    versioned

    View full-size slide

  17. Make them
    versioned,
    hackable

    View full-size slide

  18. Make them
    versioned,
    hackable &
    meaningful

    View full-size slide

  19. http://api.com/v1/

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  23. Look at URLs from a
    consumer perspective

    View full-size slide

  24. They don’t care about internal
    implementation details

    View full-size slide

  25. Use common sense

    View full-size slide

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

    View full-size slide

  27. Part 2: Verbs

    View full-size slide

  28. (in terms of model operations)

    View full-size slide

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

    View full-size slide

  30. Must at least support GET/POST

    View full-size slide

  31. Can emulate PUT/DELETE

    View full-size slide

  32. HEAD is rare and can probably
    be ignored

    View full-size slide

  33. OPTIONS is used by CORS, but
    otherwise rare

    View full-size slide

  34. Part 3: Headers

    View full-size slide

  35. Headers are important too!

    View full-size slide

  36. Some headers let you be clever

    View full-size slide

  37. 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 full-size slide

  38. Some headers reduce traffic
    (important for mobile)

    View full-size slide

  39. • 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 full-size slide

  40. Part 4: Authentication &
    Authorization

    View full-size slide

  41. OAuth2 over HTTPS

    View full-size slide

  42. OAuth2 over HTTPS
    (that’s it)

    View full-size slide

  43. Much simpler than OAuth 1.0

    View full-size slide

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

    View full-size slide

  45. Part 5: Formats

    View full-size slide

  46. Sane default: JSON, plus
    envelope with metadata

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  51. 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 full-size slide

  52. Part 6: Validity

    View full-size slide

  53. Allow your consumers to cache
    data wherever possible

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  56. Deal with preconditions and give
    appropriate response codes

    View full-size slide

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

    View full-size slide

  58. 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 full-size slide

  59. 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 full-size 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 full-size 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 full-size slide

  62. Part 7: Documentation

    View full-size slide

  63. Documentation is important

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  66. Assume nothing;
    explain everything

    View full-size slide

  67. Try building something using
    only your own API docs

    View full-size slide

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

    View full-size slide