Mobile API Sync: Mermaid Sequence Diagram

About Source

Mobile API sync describes the request-response cycle between a mobile app and a backend REST (or GraphQL) API, including the layers of caching, authentication, error handling, and retry logic that make the interaction reliable over unreliable mobile networks.

Every API request on a mobile client passes through several layers before network I/O occurs. First, an HTTP client layer (URLSession on iOS, OkHttp on Android, or a cross-platform library) checks whether a valid cached response exists for the URL. Cache validity is determined by the Cache-Control headers returned by the server on previous responses, or by an application-level TTL stored alongside the cached data. If the cache is fresh, the response is returned immediately without touching the network.

If the cache is stale or absent, the client adds authentication credentials — typically an Authorization: Bearer header — and sends the request. If the server returns a 401 Unauthorized, an auth interceptor automatically attempts to refresh the access token using the stored refresh token. On a successful refresh, the original request is retried with the new token transparently, without surfacing an error to the calling code.

Transient failures (network timeout, 5xx response) are handled by an exponential backoff retry policy. The client waits an increasing interval between retries — 1s, 2s, 4s — and gives up after a configurable maximum attempt count. If the maximum is exceeded, the error propagates to the UI layer.

On a successful 200 response, the payload is written to the local cache store and used to update the in-memory data model. The UI layer observes these model changes reactively and re-renders only the affected components.

For the offline variant of this flow where the network is unavailable, see Offline Sync Workflow. For cache eviction strategies, see Mobile Cache Strategy.

Frequently asked questions

Mobile API sync is the full request-response cycle between a mobile app and a backend API, encompassing cache lookup, authentication header attachment, token refresh on 401, exponential backoff retry on failure, and writing the response to the local cache.

The interceptor sits between the HTTP client and network layer. When a request returns a `401 Unauthorized`, it pauses the original request, calls the token endpoint with the stored refresh token, updates the stored access token, replays the original request with the new token, and returns the result — all transparently to the calling code.

Use exponential backoff for transient failures — network timeouts and 5xx server errors — where retrying immediately would likely hit the same condition. Avoid retry on 4xx client errors (except 401, handled by the auth interceptor) because those indicate a problem the client must fix, not a transient condition.

Retrying non-idempotent requests (such as POST order creation) without deduplication tokens risks duplicate side effects. Caching responses that carry user-specific or sensitive data without scoping the cache key to the user ID can leak data across account switches.

mermaid

sequenceDiagram
    participant UI as UI Layer
    participant Client as HTTP Client
    participant Cache as Local Cache
    participant Auth as Auth Interceptor
    participant API as Backend API

    UI->&gt;Client: Request data for screen
    Client->&gt;Cache: Check cache for URL
    alt Cache hit and fresh
        Cache-->&gt;Client: Return cached response
        Client-->&gt;UI: Render cached data
    else Cache miss or stale
        Cache-->&gt;Client: Cache miss
        Client->&gt;Auth: Attach Authorization header
        Auth-->&gt;Client: Bearer access_token added
        Client->&gt;API: GET /api/resource
        alt 200 OK
            API-->&gt;Client: Response payload
            Client->&gt;Cache: Write response with TTL
            Client-->&gt;UI: Return fresh data
        else 401 Unauthorized
            API-->&gt;Client: 401 token expired
            Client->&gt;Auth: Trigger token refresh
            Auth->&gt;API: POST /token with refresh_token
            API-->&gt;Auth: New access_token
            Auth-->&gt;Client: Retry original request
            Client->&gt;API: GET /api/resource with new token
            API-->&gt;Client: 200 OK with payload
            Client-->&gt;UI: Return fresh data
        else 5xx or timeout
            API-->&gt;Client: Error response
            Client-->&gt;Client: Exponential backoff retry
            Client->&gt;API: Retry GET /api/resource
            API-->&gt;Client: 200 OK
            Client-->&gt;UI: Return data
        end
    end