API Design: it's not rocket surgery (PHPNW2012)

Slide 1

Slide 1 text

API design It’s Not Rocket Surgery Dave Ingram @dmi October 6, 2012

Slide 2

Slide 2 text

Who am I? • Coder and Release Manager at GroupSpaces • Worked there for over 41/2 years • Twitter: @dmi • Github: dingram • Way too many projects of my own • Also involved in open source, including Phabricator • Occasionally found at London Hackspace

Slide 3

Slide 3 text

Feedback/thoughts on Twitter: #apirocketsurgery (or @dmi)

Slide 4

Slide 4 text

What this isn’t

Slide 5

Slide 5 text

T T REST REST REST REST REST REST REST EST EST ST ST ST T T REST REST REST REST REST REST REST REST REST REST REST REST REST REST R REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST R REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST REST R REST REST REST REST REST REST REST REST REST REST REST REST REST REST RES RES REST REST REST REST REST REST REST REST REST REST REST REST REST R R R RE RE RE RES RES REST R

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

There’s so much more!

Slide 9

Slide 9 text

URLs

Slide 10

Slide 10 text

URLs verbs

Slide 11

Slide 11 text

URLs verbs headers

Slide 12

Slide 12 text

URLs verbs headers authentication

Slide 13

Slide 13 text

URLs verbs headers authentication formats

Slide 14

Slide 14 text

URLs verbs headers authentication formats validity

Slide 15

Slide 15 text

URLs verbs headers authentication formats validity documentation

Slide 16

Slide 16 text

DOCUMENTATION

Slide 17

Slide 17 text

DOCUMENTATION (later)

Slide 18

Slide 18 text

Part 1: URLs

Slide 19

Slide 19 text

Make them versioned

Slide 20

Slide 20 text

Make them versioned, hackable

Slide 21

Slide 21 text

Make them versioned, hackable & meaningful

Slide 22

Slide 22 text

http://api.com/v1/

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

Look at URLs from a consumer perspective

Slide 27

Slide 27 text

They don’t care about internal implementation details

Slide 28

Slide 28 text

Use common sense

Slide 29

Slide 29 text

Don’t be afraid of the query string

Slide 30

Slide 30 text

Use query arguments to ﬁlter output or for (some) alternate representations

Slide 31

Slide 31 text

Good: searching & verbosity Bad: output format control (XML vs JSON)

Slide 32

Slide 32 text

Part 2: Verbs

Slide 33

Slide 33 text

(in terms of model operations)

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

Must at least support GET/POST

Slide 36

Slide 36 text

Can emulate PUT/DELETE

Slide 37

Slide 37 text

For example: POST http://api.com/foo/456!PUT POST http://api.com/foo/123!DELETE

Slide 38

Slide 38 text

Remember that POST can have side-effects and is never cached

Slide 39

Slide 39 text

PUT and DELETE are idempotent, which means they can be repeated with same effect

Slide 40

Slide 40 text

HEAD is rare and can probably be ignored

Slide 41

Slide 41 text

OPTIONS is used by CORS, but otherwise rare

Slide 42

Slide 42 text

CORS?

Slide 43

Slide 43 text

Cross-Origin Resource Sharing

Slide 44

Slide 44 text

A way to allow in-browser cross-origin XMLHTTPRequests Support: FF3.5+, Chrome 4+, Safari 4+, Opera 12+, IE8+ (partial), IE10+ (full), iOS 3.2+, Android 2.1+ http://www.w3.org/TR/cors/ http://caniuse.com/cors

Slide 45

Slide 45 text

Origin & Allow-Origin A way to allow in-browser cross-origin XMLHTTPRequests Support: FF3.5+, Chrome 4+, Safari 4+, Opera 12+, IE8+ (partial), IE10+ (full), iOS 3.2+, Android 2.1+ http://www.w3.org/TR/cors/ http://caniuse.com/cors

Slide 46

Slide 46 text

Part 3: Headers

Slide 47

Slide 47 text

Headers are important too!

Slide 48

Slide 48 text

Some headers let you be clever

Slide 49

Slide 49 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 50

Slide 50 text

Some headers reduce trafﬁc (important for mobile)

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

Beware: some proxies may not pass custom headers

Slide 53

Slide 53 text

Part 4: Authentication & Authorization

Slide 54

Slide 54 text

OAuth2 over HTTPS

Slide 55

Slide 55 text

Much simpler than OAuth 1.0

Slide 56

Slide 56 text

Many libraries for OAuth2 for many platforms as it’s a popular standard

Slide 57

Slide 57 text

If you really care about security use OAuth2-MAC

Slide 58

Slide 58 text

OAuth2-MAC uses signatures instead of bearer tokens, so secrets stay secret

Slide 59

Slide 59 text

Then again, the author of OAuth2 has now advised going back to OAuth 1.0a so YMMV

Slide 60

Slide 60 text

Part 5: Formats

Slide 61

Slide 61 text

Sane default: JSON, plus envelope with metadata

Slide 62

Slide 62 text

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

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

HATEOAS tends to be verbose and people may hate you (unless they’re building an API explorer)

Slide 65

Slide 65 text

At the very most, HATEOAS should be opt-in

Slide 66

Slide 66 text

Don’t forget: mobile bandwidth is still very limited

Slide 67

Slide 67 text

Timestamps • ISO-8601 2 12- 5- 3T19: : Z Human-readable, but needs parsing • UTC seconds since epoch: 1336 716 Easily machine-usable

Slide 68

Slide 68 text

Should your API really be human-readable? It’s better to help your consumers.

Slide 69

Slide 69 text

Part 6: Data Validity

Slide 70

Slide 70 text

Allow your consumers to cache data whenever possible

Slide 71

Slide 71 text

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

Slide 72

Slide 72 text

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

Slide 73

Slide 73 text

Deal with preconditions and give correct response codes

Slide 74

Slide 74 text

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

Slide 75

Slide 75 text

PUT /wiki/dealing -with -conflicts HTTP /1.1 Host: api.com If -Unmodified -Since: Sat , 18 Feb 2 12 11: 9:21 GMT If -Match: "x-rev -11294" Content -Type: text/html ... 412 Precondition Failed ETag: "x-rev -11467" Last -Modified: Sat , 25 Feb 2 12 14:42:53 GMT ...

Slide 76

Slide 76 text

Slide 77

Slide 77 text

Slide 78

Slide 78 text

Slide 79

Slide 79 text

New status codes in RFC6585: 428 Precondition Required 429 Too Many Requests

Slide 80

Slide 80 text

Part 7: Documentation

Slide 81

Slide 81 text

Documentation is important

Slide 82

Slide 82 text

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

Slide 83

Slide 83 text

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

Slide 84

Slide 84 text

Assume nothing; explain everything

Slide 85

Slide 85 text

Try getting people you know to build something using only your own API docs

Slide 86

Slide 86 text

Thanks! http://dmi.me.uk/talks/ Feedback via Twitter: #apirocketsurgery or @dmi Built in L ATEX Inspired by: http://goo.gl/ mT55