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

Approach Overview

• Both React Native (JS/TS runtime + native bridge) and Flutter (Dart + platform channels) can call the same REST/gRPC APIs; maximize shared code by isolating networking, models, and business rules from UI.

Maximizing Shared Code

• Extract models, validators, serializers and business logic into a single shared layer:
  • For React Native: write in TypeScript, publish as an npm package; use in RN app and expose to any Node/Deno tooling.
  • For Flutter: write in pure Dart as a package (pub).
• If you need truly single source across both, use a platform-neutral module:
  • Option A: generate client SDKs from OpenAPI/Protobuf into TS and Dart (automated, consistent).
  • Option B: implement core logic in Rust/Go, compile to native libs and expose to RN via native modules and to Flutter via FFI.

When to write Native Modules / Platform Channels

• Implement native module/channel when:
  • Platform-specific capabilities (background fetch, native auth, low-level networking, sockets) or performance-critical code (crypto, heavy parsing).
  • Shared layer via FFI is justified when logic is complex and must be identical.
• Prefer platform channels (Flutter) or Native Modules (RN) only for functionality that cannot be implemented in Dart/TS with acceptable performance.

Cross-platform Error Handling

• Define a canonical error schema (code, type, message, metadata). Serialize errors across boundaries:
  • In RN: convert native errors to JS Error objects with code/meta.
  • In Flutter: map platform channel errors to Dart exceptions with consistent types.
• Handle network retries, backoff, and cancellation in shared layer; bubble user-friendly messages to UI.

Testing & Deployment Strategies

• Unit-test shared models and business logic in respective language packages (TS and Dart) using jest and test packages.
• Contract tests using generated mock server from OpenAPI; integration tests running on CI with emulators/simulators.
• CI: build and publish shared packages (npm/pub) and run downstream app builds; include smoke tests exercising API integration.
• Use feature flags and staged rollouts for API changes; monitor metrics and error logs (Sentry) for both platforms.

This ensures consistent behavior, minimal duplication, and pragmatic use of native modules only when needed.

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.

Brief overview

• Fixed-window: counts requests per fixed interval (e.g., per minute). Simple but allows bursts at window boundaries.
• Sliding-window: smooths counts across time, preventing boundary bursts.
• Token-bucket (leaky bucket): tokens refill at a rate; client can burst up to bucket size then must wait.

How a mobile client should adapt (backoff strategies)

• Fixed-window
  • If near limit, slow or queue requests until X-RateLimit-Reset.
  • Use exponential backoff + full jitter for retries to avoid synchronized retries.
• Sliding-window
  • Respect Remaining and Reset; moderate backoff rather than large bursts—linear backoff often sufficient.
• Token-bucket
  • Track local token usage estimate; when empty, pause requests until tokens refill. Use token-aware pacing instead of retries.
• General mobile considerations
  • Honor Retry-After when provided.
  • Use exponential backoff with jitter (e.g., base 500ms, *2, randomize) to save battery and network.
  • Batch and coalesce network calls, defer non-urgent syncs to background/when on Wi‑Fi or on reconnect.

Helpful server-side headers for clients

• X-RateLimit-Limit — total allowed in window
• X-RateLimit-Remaining — requests left
• X-RateLimit-Reset — epoch seconds or delta when quota resets
• Retry-After — seconds (or HTTP-date) when next request may succeed
• Optional: X-RateLimit-Policy or X-RateLimit-Bucket to indicate algorithm/type

Why these help

• Remaining + Reset let client pace requests deterministically.
• Retry-After avoids wasted retries and reduces battery/network churn.
• Explicit policy hints let clients choose pacing strategy (burst-friendly vs smooth).

Brief approach
I’d accept an Idempotency-Key header and persist a record with request hash, status, response, timestamps. On duplicate requests return the stored response. For concurrent same-key requests use either optimistic upsert (preferred for scale) or a short DB lock.

Schema (SQL)

CREATE TABLE idempotency (
  key TEXT PRIMARY KEY,
  request_hash TEXT,
  status TEXT,       -- in_progress / completed / failed
  response JSONB,    -- cached response
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  expires_at TIMESTAMP
);

Pseudocode (optimistic upsert)

def handle_request(idempotency_key, request_body):
  req_hash = hash(request_body)
  now = now()
  expires = now + TTL

  # Try insert in_progress; if exists, read and act accordingly
  inserted = INSERT ... ON CONFLICT DO NOTHING
  if inserted:
    UPDATE idempotency SET status='in_progress', request_hash=req_hash, updated_at=now, expires_at=expires
    response = process_payment()   # actual payment call with external idempotency if available
    UPDATE idempotency SET status='completed', response=response, updated_at=now
    return response
  else:
    row = SELECT * FROM idempotency WHERE key = idempotency_key
    if row.status == 'completed' and row.request_hash == req_hash:
      return row.response
    if row.status == 'in_progress':
      wait_with_timeout_and_poll(row)   # small backoff, then re-read
    if row.request_hash != req_hash:
      return 409 Conflict

Locking vs Optimistic Upsert

• Locking (SELECT FOR UPDATE): simple, strong serialization, but reduces throughput and can cause deadlocks under high traffic.
• Optimistic upsert: higher concurrency, fewer locks, scales better; must handle races by checking status/hash and using short polling/backoff. Prefer optimistic for mobile APIs with many clients.

Expiry & Pruning

• TTL per entry (e.g., 24–72 hours) set in expires_at.
• Background job: DELETE WHERE expires_at < now() OR keep audit logs in cold storage.
• For long-running payments keep audit separate; idempotency store can be trimmed aggressively.

Scaling

• Use a fast KV store (Redis with persistence / DynamoDB / CockroachDB) for low latency.
• For Redis: use SETNX for initial reservation and a small TTL to avoid stuck in_progress; move final response to durable DB.
• Shard keys (consistent hashing) and keep entries compact.

Trade-offs / Notes

• Always combine server-side idempotency with provider-side idempotency tokens for external payment gateways.
• Use request hash to detect conflicting semantics (same key, different payload -> 409).
• Ensure TTL covers expected client retries but not indefinite storage to control cost.

This design balances safety for payments with scalability required for many mobile clients.

Overview (roles of tokens)
Access tokens: short-lived, used for API calls (minimize scope/privilege).
Refresh tokens: long-lived credential used only to get new access tokens from auth server.

Refresh token rotation

• Issue a new refresh token whenever client uses one; server marks previous token invalid (one-time use).
• Bind tokens to a client identifier and device fingerprint (e.g., install ID).
• Detect reuse: if an old refresh token is presented, revoke all sessions and force re-auth.

Secure storage on device

• iOS: store refresh tokens in Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly for background refresh scenarios.
• Android: use EncryptedSharedPreferences or KeyStore-backed storage; prefer AccountManager where available.
• Never store refresh tokens in plain files, SharedPreferences without encryption, or backups.

Refresh endpoint behavior

• Require client_id and proof (PKCE/verifier or mTLS) for public clients.
• Return new access + rotated refresh token.
• Enforce rate limits and anomaly detection (IP/device changes).

Refresh failure handling

• On invalid/reused/expired refresh tokens, clear local tokens and force full OAuth re-auth (show login).
• Gracefully handle network errors: retry with backoff but don't retry on 401 from refresh endpoint.

Common pitfalls

• Long-lived non-rotating refresh tokens — bigger attack window.
• Token reuse tolerated — allows silent takeovers.
• Storing tokens insecurely or allowing backups/exfiltration.
• Relying on device identifier alone (can be spoofed).

I would implement rotation + secure storage + clear UX for re-login to balance security and user experience.