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

Slide 1

Slide 1 text

API design More than the REST Dave Ingram @dmi February 25, 2012

Slide 2

Slide 2 text

Who am I? • Coder and Release Manager at GroupSpaces • Twitter: @dmi • Github: dingram • Also occasionally found at London Hackspace • Feedback: http://joind.in/6137

Slide 3

Slide 3 text

What this isn’t

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

There’s so much more!

Slide 8

Slide 8 text

URLs

Slide 9

Slide 9 text

URLs verbs

Slide 10

Slide 10 text

URLs verbs headers

Slide 11

Slide 11 text

URLs verbs headers authentication

Slide 12

Slide 12 text

URLs verbs headers authentication formats

Slide 13

Slide 13 text

URLs verbs headers authentication formats validty

Slide 14

Slide 14 text

URLs verbs headers authentication formats validty documentation

Slide 15

Slide 15 text

DOCUMENTATION

Slide 16

Slide 16 text

DOCUMENTATION (later)

Slide 17

Slide 17 text

Part 1: URLs

Slide 18

Slide 18 text

Make them versioned

Slide 19

Slide 19 text

Make them versioned, hackable

Slide 20

Slide 20 text

Make them versioned, hackable & meaningful

Slide 21

Slide 21 text

http://api.com/v1/

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Look at URLs from a consumer perspective

Slide 26

Slide 26 text

They don’t care about internal implementation details

Slide 27

Slide 27 text

Use common sense

Slide 28

Slide 28 text

A good routing system is your friend You don’t want to be issuing 3xx redirects because consumers forgot a slash

Slide 29

Slide 29 text

Part 2: Verbs

Slide 30

Slide 30 text

(in terms of model operations)

Slide 31

Slide 31 text

• GET = get() • PUT = set() / new Obj($id) • POST = new Obj() / doThing() • DELETE = delete() • HEAD ≈ getMetadata() • OPTIONS ≈ Reﬂection

Slide 32

Slide 32 text

Must at least support GET/POST

Slide 33

Slide 33 text

Can emulate PUT/DELETE

Slide 34

Slide 34 text

HEAD is rare and can probably be ignored

Slide 35

Slide 35 text

OPTIONS is used by CORS, but otherwise rare

Slide 36

Slide 36 text

Part 3: Headers

Slide 37

Slide 37 text

Headers are important too!

Slide 38

Slide 38 text

Some headers let you be clever

Slide 39

Slide 39 text

Accept The MIME types the client will accept. No need to use ﬁle 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.

Slide 40

Slide 40 text

Some headers reduce trafﬁc (important for mobile)

Slide 41

Slide 41 text

• ETag – A unique tag for the content • If-(None-)Match – Check ETag • If-Modified-Since – Cached by client • Cache-Control – Can it be cached?

Slide 42

Slide 42 text

Part 4: Authentication & Authorization

Slide 43

Slide 43 text

OAuth2 over HTTPS

Slide 44

Slide 44 text

OAuth2 over HTTPS (that’s it)

Slide 45

Slide 45 text

Much simpler than OAuth 1.0

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

Part 5: Formats

Slide 48

Slide 48 text

Sane default: JSON, plus envelope with metadata

Slide 49

Slide 49 text

{ "meta": { "code": 200, "dev_notes": [ "This endpoint is deprecated" ] }, "response": { ... } }

Slide 50

Slide 50 text

Use XML if you must, or if users really want it

Slide 51

Slide 51 text

Idealistic REST XML is verbose and people may hate you (unless they’re building an API explorer)

Slide 52

Slide 52 text

Don’t forget: mobile bandwidth is still very limited

Slide 53

Slide 53 text

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.

Slide 54

Slide 54 text

Part 6: Validity

Slide 55

Slide 55 text

Allow your consumers to cache data wherever possible

Slide 56

Slide 56 text

Encourage use of request headers: • GET: • If-Modified-Since • If-None-Match • POST/PUT/DELETE: • If-Unmodified-Since • If-Match

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

Deal with preconditions and give appropriate response codes

Slide 59

Slide 59 text

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

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

Slide 62

Slide 62 text

Slide 63

Slide 63 text

Slide 64

Slide 64 text

Part 7: Documentation

Slide 65

Slide 65 text

Documentation is important

Slide 66

Slide 66 text

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

Slide 67

Slide 67 text

Use examples liberally. . . and make sure they’re both up-to-date and correct!

Slide 68

Slide 68 text

Assume nothing; explain everything

Slide 69

Slide 69 text

Try building something using only your own API docs

Slide 70

Slide 70 text

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