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

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