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

API design More than the REST Dave Ingram @dmi February

25, 2012

Who am I? • Coder and Release Manager at GroupSpaces

• Twitter: @dmi • Github: dingram • Also occasionally found at London Hackspace • Feedback: http://joind.in/6137

What this isn’t

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

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

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

There’s so much more!

URLs

URLs verbs

URLs verbs headers

URLs verbs headers authentication

URLs verbs headers authentication formats

URLs verbs headers authentication formats validty

URLs verbs headers authentication formats validty documentation

DOCUMENTATION

DOCUMENTATION (later)

Part 1: URLs

Make them versioned

Make them versioned, hackable

Make them versioned, hackable & meaningful

http://api.com/v1/

http://api.com/v1/users/

http://api.com/v1/users/31337

http://api.com/v1/users/31337/posts/

Look at URLs from a consumer perspective

They don’t care about internal implementation details

Use common sense

A good routing system is your friend You don’t want

to be issuing 3xx redirects because consumers forgot a slash

Part 2: Verbs

(in terms of model operations)

• GET = get() • PUT = set() / new

Obj($id) • POST = new Obj() / doThing() • DELETE = delete() • HEAD ≈ getMetadata() • OPTIONS ≈ Reflection

Must at least support GET/POST

Can emulate PUT/DELETE

HEAD is rare and can probably be ignored

OPTIONS is used by CORS, but otherwise rare

Part 3: Headers

Headers are important too!

Some headers let you be clever

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.

Some headers reduce traffic (important for mobile)

• ETag – A unique tag for the content •

If-(None-)Match – Check ETag • If-Modified-Since – Cached by client • Cache-Control – Can it be cached?

Part 4: Authentication & Authorization

OAuth2 over HTTPS

OAuth2 over HTTPS (that’s it)

Much simpler than OAuth 1.0

Many libraries for OAuth2, as it’s a popular standard

Part 5: Formats

Sane default: JSON, plus envelope with metadata

{ "meta": { "code": 200, "dev_notes": [ "This endpoint is

deprecated" ] }, "response": { ... } }

Use XML if you must, or if users really want

it

Idealistic REST XML is verbose and people may hate you

(unless they’re building an API explorer)

Don’t forget: mobile bandwidth is still very limited

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.

Part 6: Validity

Allow your consumers to cache data wherever possible

Encourage use of request headers: • GET: • If-Modified-Since •

If-None-Match • POST/PUT/DELETE: • If-Unmodified-Since • If-Match

Return useful response headers: • Last-Modified • Expires • ETag

• Cache-Control

Deal with preconditions and give appropriate response codes

For example: ETag and Last-Modified can help prevent race conditions

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

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

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

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

Part 7: Documentation

Documentation is important

If people can’t understand your API, they won’t use it

Use examples liberally. . . and make sure they’re both

up-to-date and correct!

Assume nothing; explain everything

Try building something using only your own API docs

Thanks! http://dmi.me.uk/talks/ http://joind.in/6137 Built in L ATEX Inspired by: http://goo.gl/0mT55