Backend-for-Frontend and Client-Specific API Design Questions

Clarify goals & constraints

• Mobile apps update slowly; must preserve backward compatibility for months.
• Minimize bundle/API churn and map persisted queries to server-side implementations.

Safe schema-change rules

• Add only nullable fields or fields with server-side defaults.
• Never remove or rename fields used by older clients; use deprecation first.
• Use @deprecated(reason: "...") on fields and document removal timeline.

Persisted query versioning & mapping

• Persisted queries keyed by stable ID + semantic version (v1, v2).
• Server maps old IDs to current resolver paths via an adapter table so running clients keep working while backend evolves.
• When changing response shape, keep old resolver for legacy ID that projects fields to the new model.

Schema facades / adapter layer

• Implement a façade service that accepts legacy queries and translates them to the current schema/resolvers.
• Facade handles field renames, type conversions, and synthesizes default values for new non-nullable fields.
• Keep logic lightweight and versioned per client-min-version.

Migration timeline & policy

• Deprecation window: announce 90 days; monitor usage for 60 days; schedule removal after 180 days or when usage hits zero.
• Tie removals to app-store release targets; never remove before all supported client-min-versions can be updated.

Tooling & detection

• Instrument GraphQL gateway to record which fields and persisted query IDs are used per client version (mobile app version, OS).
• Build dashboards and alerts for deprecated-field usage.
• Add CI checks: breaking-change detector (schema diff), linting for new non-nullables, and automated tests that run legacy persisted queries against new schema via the façade.

Mobile dev practices

• Use typed client codegen (Apollo/Relay) pinned to a schema snapshot per release.
• Emit analytics with client-version + query-id to help server-side cleanup.
• When adopting new fields, feature-toggle on server and fallback gracefully in client code to preserve UX.

Approach overview
I’d design a hybrid server-side quota system (token-bucket for burst + sliding window for sustained) with enforcement at the API gateway/edge for low-latency blocking and conservative checks in downstream microservices for defense-in-depth. As a mobile developer I focus also on client behavior: transparent UX, backoff, and offline-safe fallbacks.

Enforcement points

• API Gateway / Edge proxy (primary): fast Redis-backed token bucket per (user, device, plan) for immediate accept/reject. Good for 99th-percentile latency.
• Edge caches (CDN / local proxy): short-lived counters for extreme scale.
• Microservices (secondary): strict sliding-window counters and accounting for accounting/rare bypass cases; they also emit metrics and reconcile.

Counters & data structures

• Redis keys: "quota:user:{id}:window" and "quota:device:{id}:tokens"
• Token bucket stored as {tokens, last_ts} (atomic LUA script to update)
• For sliding-window rate: fixed-size ring buffer or Redis sorted set with timestamps for precise enforcement
• Plan metadata in a small config DB/cache: burst size, refill rate, sustained QPS

Communicating limits to clients

• Standard headers on responses:
  • X-RateLimit-Limit: sustained
  • X-RateLimit-Remaining
  • X-RateLimit-Reset: seconds
  • X-Plan: name
• 429 responses include machine-readable JSON { retry_after, allowed_until, tips }
• Push plan changes via app config or silent remote feature flags

Client-side handling (mobile-focused)

• Exponential backoff + jitter on 429s; surface friendly messages only when necessary
• Local token bucket mirror (best-effort) to smooth UI: allow short bursts offline, sync with server counters on reconnect
• Queue non-urgent requests (analytics, prefetch) and send when quota available

Graceful degradation strategies

• Tiered feature prioritization: essential API calls (auth, core UX) have separate higher-priority quotas
• Degrade non-critical features first: reduce image quality, pause background syncing, batch analytics
• Feature flags to switch to low-cost modes per plan
• User messaging: unobtrusive indicators ("Sync paused to preserve plan quota") and one-tap upgrade CTA for paid plans

Metrics & reconciliation

• Emit counters and sampled request logs for chargeback and correction
• Periodic reconciliation job to fix drift and alert on abuse

This design balances low-latency enforcement, accurate accounting, and a mobile-friendly UX that gracefully degrades non-essential behavior while informing users and offering upgrade paths.

Clarify goals & constraints
Offline-first mobile notes app must allow create/edit/delete while offline, minimize data/battery, guarantee deterministic conflict resolution, and resume sync in background when connectivity returns.

Client data model

• Note: { id: UUID, title, body, updatedAt: ISO, deleted: bool, tombstoneAt?: ISO, version: int/lamport }
• Local metadata: { lastSyncedAt, pendingOps: [] }
• Persist in SQLite/Realm for durability.

Change tracking

• Append-only local operation log (pendingOps): { opId: UUID, noteId, type: create/update/delete, payload, clientTs, lamport }
• Keep tombstones for deletes until server ack.

Server API endpoints

• POST /sync/push — accept batch ops, return per-op ack + server version
• GET /sync/pull?since=timestamp — return all server-side changes since timestamp
• POST /notes/resolve — optional for manual conflict resolution audit

Sync algorithm (push/pull)

1. Background job/network callback triggers sync.
2. Push: send batched pendingOps (limited size), retry with exponential backoff, optimistic UI.
3. Server applies ops (idempotent using opId), updates server version, responds with applied list.
4. Pull: request changes since lastSyncedAt, merge into local DB, mark pendingOps as synced.
5. Resolve conflicts deterministically on client using agreed policy.

Conflict resolution approaches

• LWW (last-writer-wins): easy (use lamport or serverTs). Loses intermediate edits.
• Operational Transforms: good for rich collaborative editing; complex, needs server OT engine.
• CRDTs (recommended for notes text/blocks): converge without central ordering; use sequence CRDT (RGA/Yjs) for body, tombstone-aware for deletes. Combine with per-field LWW for metadata.
• Practical hybrid: use CRDT for body text, LWW (lamport) for title/metadata, tombstones for deletes.

Mobile specifics & best practices

• Use WorkManager (Android) / BackgroundTasks (iOS) for reliable background sync.
• Compress batches, limit frequency, respect battery/data settings.
• Provide UI conflict indicators and manual merge when automatic resolution discards content.

Error schema (summary)

• machine_code: stable programmatic code (string)
• message: human-friendly fallback (string)
• localization_key: i18n key for client lookup (string)
• http_status: numeric HTTP status
• retryable: boolean — whether client may retry automatically
• retry_after: optional seconds (integer) advising backoff
• details: array of field-level errors with { field, code, message, localization_key }

Example payload

{
  "machine_code": "PAYMENT_RATE_LIMIT",
  "message": "Too many payment attempts. Try again later.",
  "localization_key": "errors.payment.rate_limit",
  "http_status": 429,
  "retryable": true,
  "retry_after": 60,
  "details": [
    {
      "field": "card_number",
      "code": "INVALID",
      "message": "Card number failed Luhn check.",
      "localization_key": "errors.payment.card_number.invalid"
    }
  ]
}

How a mobile client should interpret fields

• machine_code: use for branching logic, analytics, feature flags, or telemetry (avoid parsing message).
• localization_key: first-choice user-facing string; fall back to message if key missing or locale missing.
• message: displayed if localization not available or for logs.
• http_status: for monitoring and conditional behavior (401 → prompt login, 4xx validation → show UI errors).
• retryable + retry_after: if retryable=true and retry_after present, schedule automatic retry after that interval (use exponential backoff if repeated); if retryable=false, do not auto-retry.
• details: map field errors to form controls; show localized inline errors using each detail's localization_key or message.

Client decision rules

• Automatic retry: only when retryable=true AND error is idempotent (GET/PUT) or server indicates safe to retry; prefer server-provided retry_after; cap retries and use exponential backoff.
• Show error immediately: validation (4xx) and authentication (401/403) — surface localized messages; attach details to fields.
• Log machine_code and http_status for analytics and debugging; avoid showing raw machine_code to users.

Clarify requirements
I’d design a cursor-based API optimized for mobile infinite-scroll: small payloads, low latency, deterministic ordering, and robust handling of dataset changes.

Request parameters

• GET /v1/items
• Query:
  • cursor (string, optional) — opaque server token
  • limit (int, optional) — client requested page size
  • snapshot_id (string, optional) — optional read-consistent snapshot token
    Example: GET /v1/items?cursor=abc&limit=25

Rules

• Server enforces max_limit = 50.
• Default limit = 20.
• Cursors are opaque, time-limited (e.g., 24h) and include last-seen item id + sort key + snapshot metadata (signed).

Sample JSON response

{
  "items": [
    {"id":"i123","title":"A","updated_at":"2026-02-28T10:00:00Z"},
    {"id":"i122","title":"B","updated_at":"2026-02-27T09:00:00Z"}
  ],
  "next_cursor":"eyJpZCI6Iml122Iiwi...signed"},
  "has_more": true,
  "limit": 20
}

Handling expired/invalid cursors

• If cursor expired/invalid -> 400 with code CURSOR_INVALID or CURSOR_EXPIRED and include fallback instructions:
  • Suggest first-page link (cursor omitted) or include a fresh snapshot token.
    Response example:

{"error":"CURSOR_EXPIRED","message":"Cursor expired; retry from start or use snapshot token"}

Mitigating duplicates/missing items

• Stable ordering: order by (primary sort key desc, unique id) to guarantee deterministic tiebreaker.
• Optional snapshot_id: server can provide a snapshot token to read a consistent view for the session; if provided, server serves from that snapshot to avoid missing/duplicated items.
• Server-side tombstones: keep deleted items as tombstones for a TTL so cursors remain valid; they can be skipped client-side but help preserve offsets.
• Client-side dedupe: mobile client should deduplicate by item id when appending pages.
• Idempotent cursors: encode last-seen item id + sort position to resume exactly.

Mobile considerations

• Keep payload small (only necessary fields).
• Preload next page when user nears end.
• Backoff and retry on cursor errors; show lightweight UI refresh if resync required.

This approach balances mobile performance, simplicity, and consistency when the underlying dataset mutates.