Mobile API Design

What it is

Mobile API design is the discipline of shaping backend APIs to serve mobile clients efficiently, taking into account their unique constraints: limited and variable bandwidth (2G/3G/4G/5G/WiFi), battery consumption (every network request drains power), variable latency (100ms on WiFi, 800ms on 3G), and the need to work across multiple client shapes (phone, tablet, watch, TV). It encompasses the Backend for Frontend (BFF) pattern for client-tailored APIs, payload optimisation techniques (sparse fieldsets, compression, binary serialisation), HTTP/2 multiplexing, request batching, and the architecture for integrating push notifications via APNs and FCM.

Why it exists

Generic REST APIs designed for desktop or server-to-server communication are often poorly suited to mobile clients. They return large, richly detailed JSON payloads when the mobile client needs only a fraction of the fields. They require multiple sequential requests to fetch the data needed for a single screen (N+1 requests). They are not designed to be called from battery-constrained devices where each HTTP connection setup has a meaningful energy cost. The BFF pattern and the optimisation techniques in this article exist to bridge this gap: the mobile client gets data in the shape it needs, at the granularity it requires, with the fewest round trips.

When to use

• Apps with multiple client types (iOS, Android, web) that have different data needs for the same domain objects.
• Apps targeting developing markets where bandwidth is expensive and 2G/3G is common.
• Apps with complex home screens that aggregate data from multiple backend services.
• Apps where battery life is a competitive differentiator (fitness trackers, always-on apps).
• Any app that sends server-initiated notifications (order updates, chat messages, breaking news).

When not to use

• A BFF per client type adds an extra service to deploy and maintain — do not add this overhead for simple apps with a single client type.
• Binary serialisation (Protocol Buffers) adds tooling complexity; for most apps, JSON with gzip compression is sufficient.
• Request batching adds client-side complexity; if most screens require a single API call, batching is unnecessary.

Typical architecture

BACKEND FOR FRONTEND (BFF) PATTERN
─────────────────────────────────────
  iOS App ───→ iOS BFF ─────┐
  Android App → Android BFF ─┼→ Product Service
  Web App ────→ Web BFF ────┘  Order Service
                               User Service

  BFF responsibilities:
  - Aggregate calls to multiple microservices
  - Shape response to exactly what the client needs
  - Handle client-specific auth (APNs/FCM token management)
  - Version independently per client

PAYLOAD OPTIMISATION
─────────────────────
  Sparse Fieldsets (REST):
    GET /products?fields=id,name,price,thumbnail_url
    → Server returns only requested fields
    → 80% payload reduction for list screens

  gzip/Brotli Compression:
    HTTP header: Accept-Encoding: gzip, br
    → Typically 60-80% reduction on JSON payloads

  Protocol Buffers (gRPC):
    Binary serialisation → 3-5x smaller than JSON
    + Faster parse time on device
    - Requires proto tooling in build pipeline

HTTP/2 BENEFITS FOR MOBILE
────────────────────────────
  Multiplexing: Multiple requests on one TCP connection
  Header compression (HPACK): Repeated headers sent once
  Server push: Proactively push resources (use sparingly)
  → Reduces TCP handshake overhead, critical on high-latency mobile

PUSH NOTIFICATION ARCHITECTURE
────────────────────────────────
  Backend Service
       ↓ device token + payload
  Notification Service (Firebase Admin SDK / APNs HTTP/2)
       ↓
  FCM (Android/cross-platform) or APNs (iOS)
       ↓
  Device

  Device token lifecycle:
  - Acquired on first app launch; sent to backend and stored
  - Expires/rotates (FCM: new token on reinstall; APNs: TokenRefresh)
  - Backend must handle InvalidRegistration → delete stale tokens
  - Topic subscription for broadcast (FCM topics, APNs broadcast)

Pros and cons

Implementation notes

API versioning for mobile: Mobile apps cannot be force-updated — old versions remain in production for months or years after a new version is released. This means the mobile API must maintain backwards compatibility or version explicitly. Use Accept: application/vnd.myapp.v2+json header versioning (or URL path versioning /v2/) and maintain at least the current and previous major version. Define a sunset policy (e.g., N-2 versions supported) and communicate it to users via in-app update prompts when an old API version is approaching deprecation.

Handling FCM token rotation: When the FCM SDK refreshes a device token, the app must send the new token to your backend. Implement a FirebaseMessagingService.onNewToken(token) handler (Android) or Messaging.messaging().apnsToken observer (iOS) that calls your backend's token registration endpoint. Your backend's notification sending logic must handle the UNREGISTERED and INVALID_ARGUMENT error codes from FCM by deleting stale tokens from the database — failing to do so causes silent notification delivery failures and inflates your registered device count.

Common failure modes

• Chatty API: A screen that requires 5+ sequential API calls to assemble its data creates high latency on mobile; consolidate into a single BFF endpoint for the screen.
• Oversized payloads: Returning full entity objects (including deeply nested relationships) when the client only needs id + name + image_url; implement sparse fieldsets or a BFF response shape.
• No retry logic: Mobile networks drop requests; the client must implement exponential back-off and retry for idempotent operations.
• Stale FCM tokens: Sending to expired tokens wastes quota and causes delivery failures; clean up tokens flagged as invalid by the FCM error response.
• Silent push for foreground data: Using silent/background notifications to deliver critical data — these are throttled by iOS and Android and are not guaranteed to be delivered promptly.

Decision checklist

• Is gzip/Brotli compression enabled on all API responses?
• Are HTTP/2 connections supported by the API server and CDN?
• For screens aggregating data from multiple services, is a BFF or GraphQL aggregation layer in place?
• Is API versioning strategy defined before the first mobile release?
• Is device token lifecycle (registration, rotation, expiry) handled end-to-end?
• Are push notification payloads designed to be actionable without requiring additional API calls?

Example use cases

• News app: Article list screen uses sparse fieldsets (?fields=id,title,thumbnail,published_at,category) to fetch only what the list view displays; full article body is fetched on tap.
• Ride-hailing app: BFF aggregates driver location, surge pricing, and estimated arrival in a single /home-screen endpoint, replacing 3 sequential calls on the client. Silent push updates driver position in the background; visual push confirms booking.
• B2B app targeting South-East Asian markets: Protocol Buffers used instead of JSON; payload reduced from 180KB to 45KB per sync; observable reduction in data costs reported in user feedback.

Related patterns

• Backend for Frontend — In-depth coverage of the BFF pattern for client-specific API tailoring.
• Push Notifications — Deep dive into APNs and FCM architectures, payload design, and opt-in UX.
• Offline-First Design — Delta sync APIs are a key enabler for efficient offline-first mobile apps.

Further reading

• Firebase Cloud Messaging — Google documentation
• UserNotifications framework — Apple Developer
• Optimising network performance for mobile — Apple Developer News