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

Goals: prevent abuse, preserve UX for mobile users on shared NATs.
Strategy:

• Multi-dimensional limits: combine per-user (user-id or account), per-device (device-id or installation-id), and per-IP (coarse) limits.
• Token-bucket per-scope: allocate burst tokens (e.g., 20 tokens) with refill rate per second/minute based on endpoint cost. Allow short bursts for interactive UX.
• Shared-network heuristics: detect NAT clusters and prefer per-user/device quotas over strict per-IP limits; when many users share IP, apply lenient per-IP caps but enforce per-user/device.
• Priority classes: critical interactives (auth, sync) get higher reserve; background syncs use lower priority and backoff on 429.
  Exposing state to client:
• Include standard headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (seconds), and a Retry-After on 429. Optionally provide X-RateLimit-Class for tier.
  Handling quota exhaustion:
• Return 429 with Retry-After and human-readable body explaining next steps and backoff. Client behavior: exponential backoff with jitter, reduce sync frequency, and queue low-priority requests; surface soft-block UI when critical.
  Implementation notes: use distributed rate-limiter (Redis token bucket or leaky-bucket with consistent hashing) with per-user keys. Log and surface metrics (top offenders, false positives) and provide admin overrides for support.

Requirements: detect regressions affecting mobile UX and enable quick rollback without full client updates.
Telemetry plan:

• Key metrics: P50/P95/P99 latency per endpoint, error rate (%) per endpoint, request success rate, sync success rate, token refresh failure rate, throttling rate, payload sizes, and mobile-specific metrics (cellular vs wifi breakdown).
• Logging: structured logs (JSON) including request id, client app version, device id (hashed), geo, latency, error codes, and stack traces for 5xx. Include sampling for high-volume endpoints but full logs for errors.
• Traces: distributed tracing (trace-id) to connect mobile SDK calls through backend services.
  Detection and rollback flow:

1. Pre-release: canary rollout (1-5% by client version or region) with elevated alerting on P95/P99/err rate and UX signals (increased session drop or decreased sync success).
2. Alerts & automated detection: threshold and change-point alerts for P99 latency or error rate increases (e.g., >50% relative increase) and anomaly detection (rolling baseline).
3. Rollback without client update: use server-side feature flags / gateway routing to switch traffic away from new code paths or disable problematic features (via config service). If gateway-level toggle insufficient, route canary percentage back to previous binary at API gateway or LB rule.
4. Emergency steps: quickly revert deployment, throttle nonessential endpoints, or serve degraded responses (cached or simplified payloads) while investigating. Notify mobile team and issue hotfix with targeted fix.
   Why: Combining fine-grained telemetry, canarying, and server-side toggles lets ops detect UX degradation and revert behavior without requiring all clients to update.

API design: use opaque resume tokens (cursor tokens) with stateless encoding and compact server verification.
Request:
GET /items?cursor=<opaque-token>&limit=50
Token contains: last_item_key, timestamp, shard_id, signature (HMAC). Server validates signature and returns next_token.
Server behavior:

• Use keyset (seek) pagination based on a monotonically ordered column (e.g., created_at + id) to avoid OFFSET. Query: WHERE (created_at,id) > (last_ts,last_id) ORDER BY created_at,id LIMIT N.
• Stateless tokens: encode position and a short TTL to avoid long-lived server state; sign tokens to prevent tampering.
• For mobile disconnects: client resumes with last token; server verifies TTL and can return a snapshot_version if required.
• To support consistency during long traversals: include a lightweight snapshot id or high-watermark (e.g., a ledger sequence number) when strong consistency needed; otherwise accept eventual consistency.
• Prevent exhausting server state: avoid server-side cursors; if server must maintain a cursor for complex queries, make them short-lived and require client heartbeats to extend; default to stateless tokens.
  Edge handling:
• Deletions: skip missing items; tokens still point to logical position.
• Reordering/new inserts: keyset handles new rows deterministically; documents inserted before cursor won’t be seen (acceptable for forward-only paging) or include since_token-based delta to capture newly inserted before cursor.
  This approach achieves efficient scans for very large sets, tolerates mobile disconnects, and limits server memory usage.

Choose GraphQL when the client needs flexible, precise payloads and multi-resource queries; choose REST when simplicity, caching, and predictable semantics matter.

Favor GraphQL (mobile reasons):

1. Complex screens needing several related resources in one request (reduces round-trips). Example: article + author + comments + related articles.
2. Multiple client types with divergent field needs (iOS/Android want different fields) — GraphQL returns exactly requested fields, saving bandwidth.
3. Rapid UI iteration where adding/removing fields should not require server version changes.

Favor REST (mobile reasons):

1. Strong HTTP caching (GET responses with Cache-Control/ETag) where CDN caching reduces mobile latency and bandwidth.
2. Simple CRUD resources and predictable endpoints for offline sync or background fetches (easier to implement delta syncs).
3. Low operational complexity when team prefers well-understood tooling, simpler rate-limiting, and stable SDKs.

Hybrid: use REST for high-traffic cached endpoints and GraphQL for client-driven complex aggregations.

Requirements: resume on flaky networks, low server cost, integrity, secure authorization.
Design:

• URL/signature scheme: client requests upload session POST /uploads with metadata (size, mime). Server returns uploadId, signed short-lived upload URL (PUT) per session or per-chunk, expiry ~15min, and chunk size recommendation. Use HMAC-signed URLs or pre-signed object storage URLs (S3 presigned PUT) tied to uploadId.
• Chunking: client splits file into fixed-size chunks (e.g., 5–10 MiB). Each chunk PUT to signed URL with headers: Upload-Id, Chunk-Index, Chunk-Size, Total-Chunks.
• Resume: server tracks uploaded chunk bitmap in a small metadata store (DynamoDB/Postgres). Client asks GET /uploads/{uploadId}/status to receive seen chunks; server returns missing ranges. Alternatively use range-based uploads with Content-Range.
• Integrity: client calculates per-chunk SHA256 and includes header X-Chunk-SHA256. Server verifies and stores chunk. After all chunks uploaded, client POST /uploads/{uploadId}/complete with manifest (chunk checksums) and overall SHA256; server composes object server-side (object storage compose) and verifies final hash.
• Authorization: upload session creation requires authenticated token. Signed URLs are short-lived and scoped to uploadId to limit misuse. For large uploads, issue multiple per-chunk URLs or a single URL that accepts Range PUTs depending on storage backend.
• Cost minimization: use object-storage multipart compose to avoid buffering on app servers; lightweight metadata service stores only small per-upload state. Reclaim stale uploads via TTL.
• Resilience: client retries chunk PUTs with exponential backoff; support parallel chunk uploads up to N connections; implement idempotent chunk PUT by chunk-index and checksum.
  Tradeoffs: smaller chunk sizes improve resume granularity but increase metadata overhead. Per-chunk signed URLs reduce attack window; server-side composition reduces egress and reassembly cost.