GOTO Berlin: DO’s and DON’Ts in a Web API

Oliver Wolf’s talk at GOTO Berlin collects a set of rules for web APIs. The main thread is to treat the web as hypermedia, design around what the client needs to do, and follow HTTP semantics instead of working against them.

Reading notes

#

• Do not think of the API as a single endpoint; connect resource representations with meaningful hypermedia links.
• Do not expose the domain model directly, because CRUD-style resources force the client to know too much about behavior and ordering.
• Design the API around intent, balancing clarity and flexibility for what the client wants to do.
• Do not misuse GET and POST; use HTTP verbs to communicate intent and expected server behavior.
• Use the full range of error codes instead of limiting responses to 200 and 500.
• Treat caching as part of the web and use cache headers and ETags to control it.
• Avoid versioning URLs; if the representation changes, use a new media type version instead.
• Use Accept and Content-Type headers for content negotiation rather than URL extensions.