An API that works well for a web client can be a poor fit for mobile. The difference is not technical sophistication; it is that you cannot force a mobile client to update, the network is hostile, and a chatty interface that is invisible on broadband is a visible delay on a train.
01You cannot deprecate what you cannot update
Web clients update on refresh. Mobile clients update when the user allows it, and a meaningful fraction never will. Assume every version you have ever shipped is still in use by someone.
This makes breaking changes categorically different. Removing a field is not a migration; it is breaking every old install permanently. The only safe changes are additive.
The practical discipline is that mobile-facing APIs need explicit versioning and a support window you actually enforce with a forced-upgrade path. Build that upgrade gate before you need it - shipping a 'please update' screen requires an app release, which is exactly what you cannot do in the emergency.
- Add fields, never remove or repurpose them. A field that changes meaning is worse than one that disappears.
- Version the API and record the app version on every request so you can measure who is still on what.
- Ship a remote kill switch and forced-upgrade check in version one. Retrofitting it requires the release you are trying to avoid.
- Make clients tolerant of unknown fields; strict parsers turn additive changes into crashes.
- Never make a client depend on field order or on a field being absent.
02Chattiness costs more than payload size
On a high-latency mobile connection, request count dominates. Six sequential requests to render a screen is six round trips, and on a poor connection that is the difference between fast and broken.
The usual fix is an aggregation layer shaped for the screen rather than the domain - one request returning what a screen needs. This is what backend-for-frontend patterns exist for, and for mobile it is often worth the extra layer.
Payload size still matters on metered connections, but the win is usually in not returning what the screen does not display. Full object graphs where the UI shows three fields waste bandwidth and leak data you did not intend to expose.
03Designing for the network you actually have
Assume requests will be interrupted mid-flight and retried. Every mutating endpoint needs an idempotency key so a retry after a timeout does not double-charge or duplicate a record. This is the single most common gap we find in mobile backends.
Distinguish errors the client should retry from errors it should not. A client that retries a validation failure forever burns battery and produces support tickets; one that does not retry a transient network failure loses work.
Return errors the client can act on. A generic message forces the app to show something unhelpful; a structured code lets it decide between retry, re-auth and surfacing a specific message.
04Auth that survives real conditions
Token refresh is where mobile auth breaks. Several requests failing simultaneously with an expired token will each trigger a refresh unless the client serialises them, and a naive implementation invalidates the token it just obtained.
Design refresh so concurrent failures share one refresh, and so a failed refresh logs out cleanly rather than leaving the app in a state where every request fails silently. Users describe this as 'the app stopped working' and it is rarely reproducible in the office.
Topics
Marcus Hale
Lead Architect · SyncTrix
Writes about the engineering decisions behind production systems - architecture, delivery and the trade-offs that only show up at scale.
Building something like this?
SyncTrix engineers AI, SaaS, platform and cloud systems for enterprises and high-growth teams. Tell us what you're shipping and we'll scope it with you.
Talk to an engineer