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. Who am I? • Coder and Release Manager at GroupSpaces

    • Twitter: @dmi • Github: dingram • Also occasionally found at London Hackspace • Feedback: http://joind.in/6137
  2. 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
  3. 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
  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. A good routing system is your friend You don’t want

    to be issuing 3xx redirects because consumers forgot a slash
  6. • GET = get() • PUT = set() / new

    Obj($id) • POST = new Obj() / doThing() • DELETE = delete() • HEAD ≈ getMetadata() • OPTIONS ≈ Reflection
  7. 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.
  8. • ETag – A unique tag for the content •

    If-(None-)Match – Check ETag • If-Modified-Since – Cached by client • Cache-Control – Can it be cached?
  9. { "meta": { "code": 200, "dev_notes": [ "This endpoint is

    deprecated" ] }, "response": { ... } }
  10. Idealistic REST XML is verbose and people may hate you

    (unless they’re building an API explorer)
  11. 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.
  12. Encourage use of request headers: • GET: • If-Modified-Since •

    If-None-Match • POST/PUT/DELETE: • If-Unmodified-Since • If-Match
  13. 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 ...
  14. 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 ...
  15. 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 ...
  16. 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 ...