A web front end can be fixed and deployed before lunch. A mobile client sits in a store review queue and then in the hands of people who never update. Every API decision has to account for that gap.
Version from the first release
Adding a version segment on day one costs nothing. Retrofitting one onto a live app with users on four different builds costs weeks.
Additive changes only
- Never remove or rename a field a shipped client reads
- Never change the type of an existing field
- New fields are optional, with a sane default when absent
- Deprecate loudly in logs long before you remove anything
Design for one screen, one call
If a screen needs four round trips to render, it will feel slow on a train regardless of how fast each call is. Shape responses around what the screen actually draws.
Make errors machine-readable
A human-readable message is for the log. The client needs a stable code it can branch on - and a flag telling it whether retrying is worth attempting.
