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

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

Dave Ingram
February 25, 2012

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

We've all heard a lot about REST APIs. But REST is not everything; there is so much more!

This was a short talk given at the PHPUK 2012 unconference.

Dave Ingram

February 25, 2012
Tweet

More Decks by Dave Ingram

Other Decks in Programming

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