API Design: It's Not Rocket Surgery
summary
Argues RESTful URLs alone are not enough and gives concrete design choices: use versioned URLs for routing and analytics, return ETag and support If-Match/If-Modified-Since for caching and conflict detection, prefer JSON with an out‑of‑band meta block (include status, deprecation, rate‑limit info and JSONP handling). Recommends OAuth2 over DIY auth, mentions HMAC only for high‑security cases, cites drop‑in rate‑limit gateways and monitoring with statsd + Graphite, and automating docs as runnable tests.
AI-written summary · about
chapters (18)
- 0:00Start
- 2:44They don't care about internal implementation details
- 2:58Use common sense
- 3:31Use query arguments to filter output or for (some) alternate representations
- 4:22Verbs
- 10:44Beware: some proxies may not pass custom headers
- 11:30Authentication & Authorization
- 15:07Formats
- 15:18Sane default: JSON, plus envelope with metadata
- 16:22Metadata envelope helps with JSONP and limited clients that discard errors
- 17:10What about XML?
- 18:04HATEOAS adds links to related endpoints in the response
- 20:36Data integrity
- 20:49Allow your consumers to cache data whenever possible
- 22:02405 Method Not Allowed 406 Not Acceptable 412 Precondition Failed 428 Precondition Required* 429 Too Many Requests
- 23:57Documentation is important
- 24:54Consider linking your examples to your automated tests
- 26:48Everybody loves graphs (and they're important for understanding API usage and performance)
related talks
52mDesigning and Implementing REST APIs For the Long Haul
49mWeb APIs that Developers Love
41mA bird's eye view on API development
54mEffective Design of RESTful APIs
50mWhat every developer should know about REST
01h 05mAPI design - tips from practice
01h 39mLet’s have some Effective REST
51mAPI Design in Real Life: What You Don't See in Books