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