APIs: the good, the bad, and the ugly

Michele Titolo @micheletitolo
Who's built, designed, and spec'd a lot of APIs
Talk will focus on web APIs, but applies to many programmatic APIs, too

Documentation

good: it exists (and bonus points if it's interactive: I/O Docs is one nice example)
bad: it doesn't get updated
ugly: documentation? Never seen a self-documenting API (hear, hear!)

URL Formats

good: consistency. The less guessing, the better. IDs, nesting are handled consistently and minimize re-learning of system quirks
bad: inconsistency. Mixing resources and IDs, for instance
ugly: using GET when mutating data

Payloads

Work in JSON: XML died. Years ago.

good: deliver the needed data (and don't overwhelm the user's monthly data)
bad: inconsistency. Different ID fields (id v. productID v. product_id). I've shipped this. It's a pain. Image URLs, dates (timezones, null, etc). You can solve this with documentation.
ugly: JSON payload containing HTML, XML wrapping XML. At some point you need to go talk.

Authentication

good: HTTP basic (SSL) is still a valid method of choice (especially on iOS 9)
bad: Oauth. It takes mobile user out of mobile experience (to web)
ugly: Bob the Builder implements his own OAuth client/server. Smart people create encryption/security schemes, and we all should let them. Custom authentication? Just don't.

Authorization

good: app requests permissions
bad: single API keys. They're easy to scrape. Anything over a wire can be man-in-the-middle'd, decrypted, and used for malicious access.
ugly: credentials leak, requests are proxied,

Errors

good: error codes (report HTTP statuses) and include a message, bonus points for human-readability (e.g. 400: what went wrong?)
bad: "bad stuff happened"
ugly: returning a 200 but have error codes in the response body OR returning HTML pages on error

Caching

good: when you have it (use Cache-control, If-modified-since, ETag) and use 304s appropriately to avoid eating users' data plans
bad: manually processing data. Client-side processing is guesswork and therefore an avoidable pain point. People are impatient, so don't test their patience processing data.
ugly: caching nothing. There's a place (protecting user data, etc) but it's rare and far between. Varnish and memcached save time, CPU, and DB I/O--take advantage.

Summary

Good APIs are consistent in structure, payload, and error-handling. Endpoints from the same API are recognizably similar
They follow conventions. How are objects formatted and should localization be handled? Are standards (HTTP) followed appropriately? Break both very, very carefully.
Keep it simple. "Self-documenting" is a myth, but spare the documentation binder.

Q + A

How do we reconcile human-readable error messages with i18n/l10n?

It's difficult. There's some useful data in HTTP headers for sniffing/setting locales, but an American browsing from a German browser may not need/want german error messages. Every platform localizes differently, so folks deploying API and implementing localization need to be in tight communication.

opinions on REST versus OData or GraphQL

Get the product definition in place and see what fits. Don't design the API (or database) without knowing what it will be used for, and then pick the one that will solve the most problems for you.

At what level do you corral developers into developing something (anything)

consistent?

People need to be talking. They need to find standards, establish standards, and follow standards (internal and external). Review can help with including as many people as possible without having 40 people in a room for a meeting. Open-ended mailing lists can be very helpful for this.

Examples of great APIs (and/or horrible APIs)

Reddit's is slow, caching is limited, but it's incredibly consistent. You receive the exact same view of posts with the exact same information. Client-side developers only need two views of posts, and it makes it very, very easy to work with.

How do you course-correct?

It takes a very long time to deprecate a public API that people are using. You can ship a new version if it's really bad, but keep it internal for as long as humanly possible. Customers break things.

But if the problem is performance, if it's caching--if the format stays the same beneath the contract, you can do anything you want. So the real question is, "where's the problem?" If it's really, really bad, yes: you do need to version.

rjz/apis.md