API Integration Patterns for Mobile Apps That Scale

Mobile API Integration Patterns That Scale

Mobile clients face flaky networks, aggressive OS background killing, and users who force-quit during uploads. API design for web CRUD does not automatically work for mobile—you need pagination, optimistic UI, and conflict resolution.

Auth and Token Refresh

Use short-lived access tokens with refresh rotation. Mobile should refresh proactively before expiry on app foreground. Queue failed requests during offline periods and replay with idempotency keys when connectivity returns.

// Axios interceptor pattern
api.interceptors.response.use(
  (res) => res,
  async (error) => {
    if (error.response?.status === 401 && !error.config._retry) {
      error.config._retry = true;
      const newToken = await refreshAccessToken();
      error.config.headers.Authorization = `Bearer ${newToken}`;
      return api(error.config);
    }
    return Promise.reject(error);
  }
);

Payload and Versioning

• Include API-Version: 2024-03-01 header or path version
• Cursor pagination—offset breaks on live feeds
• Compress large JSON with gzip—mobile pays cellular costs
• GraphQL optional for flexible screens; REST fine for most CRUD apps

Version mobile app and API together in release notes. Force upgrade only when security requires—soft nudge with grace period otherwise.

Security on Device

Certificate pinning adds MITM protection but complicates cert rotation—pin backup keys and plan rotation drills. Never store refresh tokens in AsyncStorage without encryption; use Keychain/Keystore wrappers.

Jailbreak and root detection is bypassable but raises bar for casual fraud. Combine with server-side device fingerprint and velocity checks on sensitive actions like password change or payout requests.

Log API errors with correlation IDs displayed to users on error screens—support can trace failures without guessing which request failed among thousands.

Version mobile app force-upgrade policy in writing: support N-1 on API for six months minimum unless security CVE requires hard stop. Communicate sunset dates in-app banner 30 days ahead with link to release notes explaining breaking changes clearly.

Testing Mobile Integrations

Contract tests between mobile and API teams run in CI on every PR—mobile mocks drift from API reality without automated schema validation. Use staging environment with production-like latency injected—developers on office WiFi miss timeout bugs users hit daily.

Chaos test airplane mode toggles during form submission—app should queue gracefully and resume, not lose user input silently. Support tickets about lost draft data exceed crashes in some form-heavy apps we maintain.

Retry with exponential backoff and jitter—synchronized client retries amplify outages when the server is already struggling. Show correlation IDs on error screens so support traces failures without guessing among thousands of requests.

GraphQL Considerations

If using GraphQL mobile-side, batch queries thoughtfully and avoid requesting entire object graphs on list screens. Persisted queries on CDN reduce payload size and attack surface. Rate limit by client ID—mobile apps are harder to rotate than server secrets when leaked from decompiled binaries.

Document expected offline behavior in API README—mobile teams implement queues assuming idempotent POST when server does not guarantee it. Clarify which endpoints support Idempotency-Key header and which do not before mobile v1 ships to thousands of users.

Publish mobile-specific error code appendix—HTTP status alone insufficient when 422 validation errors return field map JSON mobile must parse consistently across API versions documented semver changelog.

Version minimum supported app in API responses—server can warn deprecated clients with header prompting upgrade before breaking change deploy rather than silent failure confusing users on old builds still in market.

Hold thirty-minute mobile/backend office hours monthly to review upcoming API changes before sprint commitment. Skipped meetings cause week-long rework when response shapes shift without mobile in the planning room.

Contract Tests

Mobile contract tests against OpenAPI specs catch breaking field renames before store submission. Log latency percentiles by app version—Android-only spikes often trace to TLS or pinning changes, not the server.

Frequently Asked Questions

REST vs GraphQL on mobile?

GraphQL reduces over-fetching on complex home screens. REST simpler for teams without GraphQL ops maturity.

How handle offline mode?

Local SQLite/WatermelonDB cache with sync queue. Show clear offline indicators—never silent failures.

Should mobile call third-party APIs directly?

No—proxy through your backend to hide keys and enforce business rules.