Web front ends and their APIs can be deployed together. Mobile apps cannot: some users will run a version from last year for a long time. On top of that, requests travel over networks that drop, slow down and retry. An API built only for the web tends to break in both situations.
Version from the start
We version APIs from the first release and keep old versions running while meaningful numbers of users still need them. App versions report themselves in every request, so we know exactly when an old version can be retired.
Make retries safe
When a request times out, the app does not know whether the server received it. Without care, a retry creates a second order or a second payment.
POST /v2/orders
Idempotency-Key: 7f3c2a90-4b1e-4d2a-9e51-0c8d2f6b1a44
// same key twice → same order returned, nothing created twiceSend less, less often
- Shape responses for screens, so one screen needs one request.
- Support partial updates and delta sync instead of full reloads.
- Compress responses and paginate everything that can grow.
- Return errors with codes the app can act on, not just messages.