API Design: It's Not Rocket Surgery (ODI)

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

View Slide

Who am I?
• Was developer/RM at GroupSpaces for 41/2 years
• Now DevOps freelancer
• Twitter: @dmi
• Github: dingram
• Way too many projects
• Involved in open source, including Phabricator
• Occasionally found at London Hackspace

View Slide

Why am I giving this talk?
• I’ve built a number of APIs
• Both for GroupSpaces and my own projects
• Sadly most are not public (yet!)
• I’m also a consumer of many other APIs
• Twitter
• Foursquare
• Tumblr
• TfL
• Spotify
• . . . blah blah blah. . .

View Slide

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

View Slide

What this isn’t

View Slide

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

View Slide

There’s so much more!

View Slide

URLs

View Slide

URLs
verbs

View Slide

URLs
verbs
headers

View Slide

URLs
verbs
headers
authentication

View Slide

URLs
verbs
headers
authentication
formats

View Slide

URLs
verbs
headers
authentication
formats
integrity

View Slide

URLs
verbs
headers
authentication
formats
integrity
documentation

View Slide

DOCUMENTATION

View Slide

DOCUMENTATION
(later)

View Slide

Part 1: URLs

View Slide

Make them
versioned

View Slide

Make them
versioned,
hackable

View Slide

Make them
versioned,
hackable &
meaningful

View Slide

http://api.com/v1/

View Slide

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

View Slide

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

View Slide

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

View Slide

Look at URLs from a
consumer perspective

View Slide

They don’t care about
internal implementation
details

View Slide

Use common sense

View Slide

Don’t be afraid of
the query string

View Slide

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

View Slide

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

View Slide

Good:
http://api.com/v1/search?q=foobar
Bad:
http://api.com/v1/search/foobar

View Slide

Good:
http://api.com/v1/foo.json
Bad:
http://api.com/v1/foo?format=json

View Slide

Part 2: Verbs

View Slide

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

View Slide

Must at least handle GET/POST

View Slide

Can emulate PUT/DELETE

View Slide

For example:
POST http://api.com/v1/foo/42!PUT
POST http://api.com/v1/foo/11!DELETE

View Slide

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

View Slide

PUT and DELETE are
idempotent, which means
they have the same effect
even if they’re repeated

View Slide

HEAD is rare and
can probably be ignored

View Slide

OPTIONS is used by CORS,
but otherwise rare

View Slide

CORS?

View Slide

Cross-Origin Resource Sharing

View Slide

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

View Slide

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

View Slide

Part 3: Headers

View Slide

Headers are important too!
(and you can be clever)

View Slide

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.

View Slide

Some headers reduce trafﬁc
(important for mobile)

View Slide

• ETag – A unique tag for the content
• If-(None-)Match – Check ETag
• If-(Un)Modified-Since – Is it newer?
• Cache-Control – Can it be cached?
• Expires – How long is it valid?
• Vary – Additional caching rules

View Slide

Beware: some proxies may
not pass custom headers

View Slide

Beware: even some standard
headers are not safe

View Slide

Prefer headers, but accept
other methods

View Slide

Part 4: Authentication &
Authorization

View Slide

OAuth2 over HTTPS

View Slide

Much simpler than OAuth1
(similar to session cookies)

View Slide

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

View Slide

For extra security
use OAuth2-MAC

View Slide

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

View Slide

Then again, the author of OAuth2 has now
advised not upgrading from OAuth 1.0a
and either using OAuth 1.0a for new sites
or staying close to a large provider’s
implementation

View Slide

No need to worry about
rate-limiting (to start with*)
3scale, Apiaxle, Mashery can help

View Slide

Part 5: Formats

View Slide

Sane default: JSON, plus
envelope with metadata

View Slide

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

View Slide

Metadata envelope helps
with JSONP and limited
clients that discard errors

View Slide

Having metadata allows
out-of-band information, like
deprecation warnings

View Slide

What about XML?

View Slide

*Hypertext as the Engine of Application State
HATEOAS* is a nice idea,
although it’s very verbose
(but useful for building an API explorer)

View Slide

HATEOAS adds links to related
endpoints in the response

View Slide

At the very most,
HATEOAS should be opt-in
for clients that will use it

View Slide

Don’t forget: mobile
bandwidth is still very limited

View Slide

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

View Slide

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

View Slide

Part 6: Data integrity

View Slide

Allow your consumers
to cache data
whenever possible

View Slide

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

View Slide

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

View Slide

Deal with preconditions and
give correct response codes

View Slide

Useful status codes:
4 5 Method Not Allowed
4 6 Not Acceptable
412 Precondition Failed
428 Precondition Required*
429 Too Many Requests*
*New in RFC6585

View Slide

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

View Slide

PUT /v1/wiki/dealing -with -conflicts HTTP /1.1
Host: api.com
Content -Type: text/html
...
428 Precondition Required
ETag: "x-rev -11294"
Last -Modified: Sat , 18 Feb 2 12 11: 9:21 GMT
...

View Slide

PUT /v1/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
...

View Slide

Part 7: Documentation

View Slide

Documentation is important

View Slide

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

View Slide

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

View Slide

Assume nothing;
explain everything

View Slide

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

View Slide

Be helpful: provide an
interactive console
e.g. Apiary, Apigee console, Mashery’s iodocs

View Slide

And ﬁnally: Statistics

View Slide

Record numbers for anything
and everything you can
imagine

View Slide

Everybody loves graphs
(and they’re important for understanding
API usage and performance)

View Slide

Things to measure
Counters:
HTTP status (200, 400, 500, . . . )
Tokens issued
Token refreshes
Clients created
Client usage
Auth successes
Auth failures
Auth grants
Auth rejections
DB queries
API version/release
Client type
. . .
Avg response time:
Auth requests
General requests
Speciﬁc subsystems
. . .
Other
Memory usage
Client location
. . .

View Slide

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

View Slide

API Design: It's Not Rocket Surgery (ODI)

API Design: It's Not Rocket Surgery (ODI)

Dave Ingram

More Decks by Dave Ingram

Other Decks in Programming

Featured

Transcript