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.

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