API Design 2025 FAQ & Answers

Richardson Maturity Model (RMM) classifies REST APIs based on adherence to RESTful principles across four levels. Created by Leonard Richardson (2008). Breaks REST into three key elements: resources, HTTP verbs, hypermedia controls. Four levels: (0) Swamp of POX - single URI, single HTTP method (POST), (1) Resources - multiple URIs per resource, (2) HTTP Verbs - proper use of GET/POST/PUT/DELETE/PATCH, (3) HATEOAS - hypermedia controls in responses. 2025 adoption: Level 2 most common in production, Level 3 (full REST) still rare due to complexity. Roy Fielding states Level 3 is prerequisite for true REST. Use RMM to assess API maturity and plan improvements. Level 2 balances simplicity with RESTful principles.

Level 0 (Swamp of POX): Single URI endpoint, one HTTP method (typically POST), RPC-style. All operations to same endpoint. Level 1 (Resources): Multiple resource URIs, divide-and-conquer approach, still mostly POST. Example: /orders, /customers (separate resources). Level 2 (HTTP Verbs): Proper HTTP methods - GET (read), POST (create), PUT/PATCH (update), DELETE (remove). Correct status codes (200, 201, 404). Most production APIs here. Level 3 (HATEOAS): Responses include hypermedia links for available actions. Client discovers API through links. Example: Order response includes links to cancel, ship, refund. 2025 reality: Aim for Level 2 minimum, Level 3 if building hypermedia-driven API. Level 2 is production standard.

HATEOAS (Hypermedia As The Engine Of Application State) is Level 3 of Richardson Maturity Model where responses include hypermedia links showing available next actions. Client navigates API by following links, not hardcoding URLs. Example using HAL format: GET /orders/123 returns {"id":123, "status":"pending", "_links":{"self":"/orders/123", "cancel":{"href":"/orders/123/cancel", "method":"POST"}, "pay":"/orders/123/payment"}}. Benefits: (1) API evolvable - change URLs without breaking clients, (2) Self-documenting - discoverable actions, (3) Decoupling - no hardcoded business logic. 2025 trends: Growing adoption for AI agent navigation where agents discover endpoints through hypermedia controls. Common formats: HAL (JSON+links), Siren, JSON:API. Use when: Building evolvable public APIs, AI-accessible services, or complex workflows requiring dynamic navigation. Most internal APIs remain at Level 2 (sufficient for controlled clients).

Three main strategies: (1) URI versioning - /v1/orders, /v2/orders. Most common, best discoverability, cache-friendly. Used by Twitter, Facebook, Airbnb. (2) Header versioning - Api-Version: 2 or Accept: application/vnd.api.v2+json. Cleaner URIs, content negotiation support. (3) Query parameter - /orders?version=2. Simplest but poor routing support. 2025 best practices: Use URI versioning for public APIs (/v1/, /v2/). Version only on breaking changes (12-18 month cycles). Communicate deprecation with Sunset: Sat, 31 Dec 2025 23:59:59 GMT header. Support old version 12+ months minimum. Avoid: Mixing strategies, versioning non-breaking changes, >2 active versions. Breaking changes: Field removal, type changes, new required parameters. Non-breaking: New optional fields, new endpoints. Use semantic versioning (MAJOR.MINOR.PATCH) for clear change communication.

Essential status codes for 2025: 2xx Success: 200 OK (GET success), 201 Created (POST success, return Location header), 204 No Content (DELETE success). 4xx Client Errors: 400 Bad Request (validation failure), 401 Unauthorized (missing/invalid auth), 403 Forbidden (authenticated but not authorized), 404 Not Found (resource doesn't exist), 409 Conflict (state conflict, e.g., duplicate), 422 Unprocessable Entity (semantic validation failure), 429 Too Many Requests (rate limit). 5xx Server Errors: 500 Internal Server Error (server bug), 502 Bad Gateway (upstream failure), 503 Service Unavailable (temporary downtime). Don't: Abuse 200 for errors, return 500 for validation failures. Use RFC 7231 standard codes. Include error details in response body with code, message, field errors.

Idempotent operation produces same result when repeated multiple times. Critical for reliability - safe to retry without side effects. HTTP methods: GET, PUT, DELETE, HEAD, OPTIONS are idempotent. POST is NOT idempotent. GET /orders/123 - always returns same order (until modified). PUT /orders/123 - updating same data multiple times has same effect as once. DELETE /orders/123 - deleting multiple times same as deleting once (404 after first). POST /orders - creates new order each time (NOT idempotent). 2025 pattern: For non-idempotent operations (POST), use idempotency keys in header (Idempotency-Key: uuid). Server deduplicates requests with same key. Essential for payment APIs, critical operations. Implementation: Store key + response in cache (Redis), return cached response for duplicates within time window (24 hours).

PUT replaces entire resource (full update), PATCH applies partial modifications. PUT /orders/123 with {"status":"shipped", "total":100} replaces entire order (must send all fields). PATCH /orders/123 with {"status":"shipped"} updates only status field. PATCH formats: (1) JSON Merge Patch (RFC 7396, Content-Type: application/merge-patch+json) - simple, send partial object, null deletes field. Limitation: can't set field to null. (2) JSON Patch (RFC 6902, Content-Type: application/json-patch+json) - operation list [{"op":"replace", "path":"/status", "value":"shipped"}]. More powerful, supports test/move operations. 2025 recommendation: Use PATCH with JSON Merge Patch for simplicity (mobile bandwidth savings, fewer fields). Use PUT only when full replacement semantically correct. PUT is idempotent, PATCH idempotency depends on format. Return 200 with updated resource or 204 No Content.

N+1 problem: Query fetches list of N items with one query, then issues N additional queries for related data. Example: Fetch 100 users (1 query), then fetch posts for each user (100 queries) = 101 total queries. Causes: GraphQL field resolvers run independently, no automatic batching, nested resolvers fire per parent item. Impact: Severe performance degradation, database overload, slow response times. Example query causing N+1: {users {name posts {title}}} fires: SELECT * FROM users, then SELECT * FROM posts WHERE userId=1, userId=2, ..., userId=100 (100 separate queries). 2025 solution: Use DataLoader pattern to batch and cache requests. Essential to fix before production - can cause 10-100x performance degradation. Monitor with GraphQL query complexity analysis.

DataLoader batches multiple load requests into single batch operation and caches results per request. Pattern: Instead of N database queries, collects all keys during request, executes one batched query. Implementation: Create DataLoader instance per request (not globally), define batchLoadFn(keys) that fetches multiple records, call loader.load(key) in resolvers. Example: const userLoader = new DataLoader(async (userIds) => db.users.findByIds(userIds)); then loader.load(1), loader.load(2) batches into single findByIds([1,2]) call. Benefits: O(N^2) reduced to O(1) concurrency, request-level caching prevents duplicate fetches. 2025 enhancement: WunderGraph DataLoader 3.0 uses breadth-first loading (5x faster). Use in every resolver, even non-list fields. Available in all GraphQL server libraries. Essential for production GraphQL APIs.

GraphQL Federation composes multiple GraphQL services (subgraphs) into single unified graph (supergraph) via gateway. Developed by Apollo, evolved from v1.0 (2019) to v2.0 (2022). Benefits: (1) Team autonomy - independent subgraph ownership/deployment, (2) Incremental adoption - add services gradually, (3) Unified schema - single endpoint for clients. Pattern: Define entities with @key directive (service User @key(fields: "id")), extend in other services (@extends type User @key(fields: "id") {orders: [Order]}), gateway routes queries to appropriate subgraphs. Use when: Microservices architecture (>5 services), multiple teams, need BFF replacement, enterprise scale. Adoption: Netflix, Expedia, Volvo, Booking use federation. 2025 status: GraphQL Foundation standardizing patterns via Composite Schema Working Group. Tools: Apollo Federation 2.0, WunderGraph Cosmo, The Guild Federation. Don't use: Single service, <3 teams, simple monolithic API.

Create DataLoader instance per request in context with batch function. Steps: (1) Define batchLoadFn accepting array of keys, returning array of values in same order. (2) Create DataLoader in per-request context. (3) Use loader.load(key) in resolvers. TypeScript example: const userLoader = new DataLoader<number, User>(async (ids) => { const users = await db.users.findByIds(ids); return ids.map(id => users.find(u => u.id === id) || new Error('Not found')); }). Context: { dataSources: { userLoader: new DataLoader(...) } }. Resolver: return context.dataSources.userLoader.load(userId). Batching window: Single event loop tick (automatic). Caching: In-memory per request, use loader.clear(key) to invalidate. 2025 best practice: TypeScript for type safety, factory functions per entity type, batch with SQL IN clause. Result: 13 queries reduced to 3-4. Essential for production GraphQL APIs.

Key practices: (1) Nullable by default - bias toward nullable output fields (handle partial results), non-null input fields (explicit requirements). Yelp guideline: never make promises you can't keep. (2) Connection pattern - use edges/nodes/pageInfo for pagination (type UserConnection { edges: [UserEdge!]!, pageInfo: PageInfo! }). (3) Input types - wrap mutation arguments in input objects (mutation createUser(input: CreateUserInput!): User). Improves evolution, validation. (4) Descriptive types/enums - Apollo 2025 report: 30% fewer client errors with clear types. (5) Demand-driven schema - design for client needs, not database structure. Naming: Verbs for mutations (createUser, updateOrder), nouns for queries (user, orders). Avoid: Deep nesting (>3 levels), exposing DB schema, nullable lists. Tools: GraphQL Codegen (type generation), Apollo Studio (schema registry), Pothos (code-first builder). Essential for production maintainability.

No, GraphQL isn't universal. Use GraphQL when: (1) Complex UI with varying data needs (dashboards, e-commerce), (2) Multiple client types (web/iOS/Android) need different data shapes, (3) Frequent requirement changes, (4) Aggregate multiple data sources, (5) Mobile bandwidth matters (fetch only needed). Don't use when: (1) Simple CRUD (REST faster), (2) File uploads/downloads (limited multipart support), (3) Team unfamiliar (learning curve), (4) Caching critical (HTTP caching simpler). 2025 reality: 61% organizations use GraphQL (Postman survey), but REST remains dominant for public APIs. Pattern: Hybrid approach - REST for core public resources, GraphQL for internal apps/aggregation, gRPC for backend services. Example: Netflix uses GraphQL (recommendations), REST (account management). Trade-offs: GraphQL complexity (schema management, N+1, caching) vs flexibility. Start REST, migrate when complexity justifies (typically >10 endpoints, >3 client types).

WunderGraph DataLoader 3.0 uses breadth-first loading instead of depth-first, achieving 5x performance improvement. Traditional depth-first: Loads data level by level, waits for each level, O(N^2) concurrency bottleneck. Breadth-first: Two-step process - (1) Walk query plan breadth-first, identify all needed data from subgraphs, merge into single JSON object. (2) Generate response depth-first according to GraphQL query structure. Benefits: Reduces concurrency from O(N^2) to O(1), loads all required data in single pass, eliminates need for traditional DataLoader pattern, no concurrency needed for sibling field batching. Performance: 5x faster measured, gap increases with list size and nesting levels. Presented at GraphQLConf 2023, implemented in WunderGraph Cosmo Router (open source). Use when: Performance critical, deep nesting, Federation architecture. Backward compatible with DataLoader APIs. Essential for high-scale GraphQL (>10k req/s).

gRPC is high-performance RPC framework using HTTP/2 and Protocol Buffers. Created by Google, optimized for microservices. Benefits: (1) Performance - 5-10x faster than REST, binary serialization, (2) Streaming - bidirectional, client, server streaming built-in, (3) Type safety - strongly typed with protobuf contracts, (4) Code generation - automatic client/server code from .proto files. Use when: Internal microservices, low latency requirements (<10ms), high throughput (>10k req/s), real-time data (IoT, telemetry, chat), polyglot services (protobuf supports 10+ languages). Don't use: Public APIs (browser support limited), simple CRUD (REST easier), mobile-only (bandwidth savings minimal). 2025 pattern: gRPC for backend services, REST/GraphQL for external APIs. Essential for performance-critical systems.

Protocol Buffers (protobuf) is binary serialization format developed by Google. Language-agnostic, platform-neutral. Define schema in .proto files with messages and services. Benefits: (1) Performance - 6x faster parsing than JSON, (2) Size - 60% smaller payloads for complex messages, (3) Type safety - strongly typed, code generation, (4) Backward/forward compatibility - versioning built-in. Example: message User {int32 id=1; string name=2; repeated string emails=3;}. Compiler generates code for 10+ languages. Trade-offs: Not human-readable (binary), requires schema, tooling needed for debugging. 2025 usage: gRPC services, high-throughput systems, mobile apps (bandwidth savings). Alternative: JSON for readability, protobuf for performance. Use with gRPC for 5-10x performance gain over JSON/REST.

gRPC supports four streaming patterns: (1) Unary - traditional request/response (no streaming), (2) Server streaming - client sends one request, server streams multiple responses (stock tickers, log tailing), (3) Client streaming - client streams multiple requests, server sends one response (file upload, batch processing), (4) Bidirectional streaming - both client and server stream messages independently (chat, real-time collaboration, multiplayer games). Streaming uses single HTTP/2 connection, no reconnection overhead. Benefits: Low latency, efficient bandwidth usage, native flow control. Implementation: Define in .proto file: rpc StreamData (stream Request) returns (stream Response). 2025 use cases: IoT telemetry (server streaming), chat apps (bidirectional), video calls (bidirectional). Essential for real-time systems where WebSockets traditionally used.

Bidirectional streaming allows client and server to send messages independently over single HTTP/2 connection via read-write streams. Both sides read/write in any order, fully asynchronous. HTTP/2 enables multiplexing (multiple streams on one TCP connection), each stream sends data bidirectionally. Pattern: Client opens stream, both sides send/receive independently, no request/response coupling. Implementation: Define in .proto: rpc Chat(stream Message) returns (stream Message). Use async iterators for read/write. Example: Client stream.write(msg), server independently stream.write(response). Use cases: Real-time chat (simultaneous send/receive), live collaboration (Google Docs style), multiplayer games (player actions + game state), IoT monitoring (device sends telemetry, server sends commands), ride-hailing (client location, server updates charge/distance). Benefits: Single connection (low overhead), no polling, native flow control, backpressure. 2025 status: Cloud Run supports bidirectional gRPC, replacing WebSockets in microservices.

gRPC is 5-10x faster than REST in most benchmarks. Specific improvements: (1) Parsing - protobuf 6x faster than JSON parsing, (2) Payload size - 60% smaller for complex messages (binary vs text), (3) Connection - HTTP/2 multiplexing vs HTTP/1.1 (single connection for multiple requests), (4) Latency - measured 67% faster in benchmark tests. Why: Binary serialization (protobuf) vs JSON, HTTP/2 features (header compression, multiplexing), efficient encoding. Trade-offs: gRPC requires HTTP/2, limited browser support, not human-readable. 2025 use: gRPC for internal services where performance critical (financial transactions, real-time systems, high-throughput APIs >10k req/s). REST for external APIs, simple services. Hybrid common: gRPC backend, REST/GraphQL gateway for clients. Don't optimize prematurely - measure first.

Generally no, but possible with gRPC-Web or ConnectRPC. Challenges: (1) Browser support - browsers don't support HTTP/2 gRPC directly, impossible to implement gRPC spec without proxy. (2) Tooling - limited debugging vs REST (Postman, curl). (3) Discoverability - no OpenAPI equivalent. Solutions: (1) gRPC-Web - official proxy (Envoy default), limited to unary + server streaming (no bidirectional), base64-encoded payloads. (2) gRPC-Gateway - translates REST/JSON to gRPC automatically via protobuf annotations. (3) ConnectRPC (2025 modern) - JSON-based protocol over HTTP, supports all three protocols (gRPC, gRPC-Web, Connect) with single server. Best practice: Internal services use gRPC, API Gateway translates to REST/GraphQL for external clients. Alternative: Provide both interfaces (Google Cloud pattern). Use gRPC publicly only if: Performance critical, mobile SDK (control both ends), TypeScript/Buf toolchain. Don't force external developers into gRPC complexity.

PKCE (Proof Key for Code Exchange, pronounced 'pixie') prevents authorization code interception attacks. How it works: (1) Client generates code_verifier (random string), (2) Creates code_challenge = hash(code_verifier), (3) Sends code_challenge with authorization request, (4) Receives authorization code, (5) Sends code + code_verifier to token endpoint, (6) Server verifies hash(code_verifier) == code_challenge. Attack prevented: Attacker intercepts authorization code but can't exchange it without code_verifier (not transmitted in authorization request). Originally for public clients (mobile, SPA), now mandatory for all clients in OAuth 2.1. Implementation: Use S256 method (SHA256), not plain. Generate cryptographically random code_verifier (43-128 chars). 2025 requirement: All OAuth flows must use PKCE. Essential security for mobile and web apps.

Key security practices: (1) Rotation - issue new refresh token with each use, invalidate old one (prevents replay attacks), (2) Storage - never localStorage/sessionStorage (XSS vulnerable), use httpOnly secure SameSite cookies or server-side storage, (3) Expiration - long-lived but not infinite (30-90 days typical), (4) Binding - bind to client instance (rotation provides this), (5) Revocation - support immediate revocation (logout, security events). Pattern: Client uses refresh token → Server issues new access token + new refresh token, invalidates old refresh token. Detect reuse: If old refresh token used again, revoke entire family (security breach). 2025 best practice: Automatic rotation (OAuth 2.1 recommendation), httpOnly cookies for web, secure storage for mobile. Don't: Reuse refresh tokens, store in browser storage, make them never expire. Essential for secure authentication.

Refresh token rotation issues new refresh token every time it's used, invalidating previous one. Pattern: Client sends refresh token → Server validates, issues new access token + new refresh token → Client stores new refresh token, discards old → Old refresh token now invalid. Benefits: (1) Limits replay attacks - stolen token only works once, (2) Detects breaches - if old token reused, indicates theft (revoke token family), (3) Reduces blast radius - compromised token has single use. Implementation: Store token family ID, track rotation chain, detect reuse (flag security event). Reuse detection: If revoked refresh token used, assume compromise, invalidate all tokens in family, force re-authentication. 2025 standard: Recommended for all apps, mandatory for high-security. SPAs and mobile apps must use rotation. Essential security pattern for refresh tokens.

Short-lived access tokens are critical security practice. Recommendations: (1) High security - 15-30 minutes (banking, healthcare, admin panels), (2) Standard security - 1 hour (typical web apps, APIs), (3) Low security - 24 hours maximum (internal tools, low-risk). Never: >24 hours or no expiration. Why short-lived: Limits window if token stolen, forces refresh (enables rotation/revocation), reduces blast radius of compromise. Pattern: Short access token (15-60 min) + long refresh token (30-90 days). Client refreshes access token before expiry using refresh token. Trade-offs: More refresh requests (handled transparently), better security. 2025 standard: 15 minutes for sensitive operations, 1 hour for general use. Use refresh tokens for long sessions. Don't use long-lived access tokens - security risk outweighs convenience.

No, localStorage is vulnerable to XSS attacks. Any JavaScript on page can read localStorage (including malicious scripts from compromised dependencies, ads, or XSS vulnerabilities). Better options: (1) httpOnly cookies - JavaScript can't access, immune to XSS, browser sends automatically. Set Secure (HTTPS only), SameSite=Strict/Lax (CSRF protection). (2) Memory only - store in JavaScript variable, lost on refresh (acceptable for SPAs with refresh tokens in httpOnly cookies). (3) SessionStorage - slightly better than localStorage (cleared on tab close) but still XSS vulnerable. 2025 best practice: Access tokens in httpOnly cookie or memory, refresh tokens in httpOnly cookie only. Never localStorage/sessionStorage for any tokens. Trade-off: Cookies vulnerable to CSRF (mitigate with SameSite), but XSS is more common threat. Don't: Store sensitive tokens in browser storage accessible to JavaScript.

Critical practices: (1) Algorithm verification - explicitly specify allowed algorithms (RS256, ES256), reject unexpected algorithms (prevents algorithm confusion attacks), (2) Never include secrets - JWTs are base64-encoded, not encrypted, readable by anyone, include only user ID, roles, expiration, (3) Short expiration - 15-60 minutes maximum, use refresh tokens for longer sessions, (4) Verify signature - always validate signature before trusting claims, (5) Verify claims - check iss (issuer), aud (audience), exp (expiration), nbf (not before). Don't: Use HS256 with shared secret in public clients, include passwords/PII in payload, skip signature verification, use long expiration (>24h). 2025 recommendation: Use RS256 (asymmetric) for microservices, ES256 for performance, HS256 only for trusted environments. Validate thoroughly - never trust JWT contents without signature verification.

Token bucket allows controlled bursts while enforcing average rate limit. How it works: (1) Bucket holds tokens (max capacity = burst size), (2) Tokens added at constant rate (refill rate = requests per second), (3) Each request consumes one token, (4) Request allowed if token available, rejected if bucket empty. Example: Bucket capacity 100, refill rate 10/sec. Client can burst 100 requests immediately, then sustained 10 req/sec. After idle period, bucket refills to 100. Benefits: Handles burst traffic (product launches, login spikes), smooth average rate, flexible. Use when: Burst allowances needed, traffic spiky. Implementation: Store (tokens, last_refill_time) per client in Redis. On request: refill tokens based on elapsed time, check if tokens >= 1, decrement if allowed. 2025 standard: Preferred for APIs with burst patterns.

Sliding window tracks requests in moving time window, providing accuracy without fixed window boundary issues. How it works: Use sorted set in Redis storing request timestamps. On request: (1) Remove timestamps older than window (ZREMRANGEBYSCORE), (2) Count requests in window (ZCARD), (3) Allow if count < limit, (4) Add current timestamp (ZADD). Example: 100 requests per minute. Window slides continuously - if 100 requests at :00-:30, new requests allowed at :01 (oldest timestamp :00 dropped). Benefits: More accurate than fixed window (no boundary reset spike), automatic cleanup of old timestamps, fair distribution. Trade-off: More memory than token bucket. Implementation: Redis sorted sets, Lua script for atomicity. Use when: Need accuracy, prevent gaming of fixed windows, unpredictable traffic. 2025 recommendation: Default choice for rate limiting.

Redis provides fast, distributed rate limiting for microservices. Pattern: (1) Use Redis as centralized counter store, (2) All service instances increment same counters (consistent view), (3) Set TTL for automatic cleanup. Implementation for sliding window: Use sorted sets, Lua script for atomicity. Script: ZREMRANGEBYSCORE key 0 (now-window), count=ZCARD key, if count<limit then ZADD key now uuid, EXPIRE key window. For token bucket: Store {tokens, last_refill} as hash, Lua script to refill and check. Benefits: Atomic operations (no race conditions), distributed (works across instances), fast (<1ms), automatic expiry (TTL). 2025 pattern: Use Lua scripts to ensure atomicity, configure Redis persistence for durability, use Redis Cluster for high availability. Libraries: node-rate-limiter-flexible, express-rate-limit with Redis store. Essential for production rate limiting.

Use sliding window for production public APIs. Fixed window: Resets at fixed intervals (every minute at :00), simple, low memory. Critical flaw: Boundary exploitation - 100 req/min limit allows 200 requests in 2 seconds (100 at :59, 100 at :01). Sliding window: Continuous rolling window, tracks individual request timestamps in Redis sorted set, prevents gaming. Accurate but more memory. Implementation: ZREMRANGEBYSCORE (remove old), ZCARD (count), ZADD (add timestamp), EXPIRE (cleanup). Comparison: Fixed window - simple, predictable, memory efficient, vulnerable to bursts. Sliding window - fair, accurate (requests limited in any rolling minute), prevents gaming, higher memory. 2025 updates: Redis 8 HEXPIRE command simplifies field-level expiration for hash-based rate limiting. Recommendation: Sliding window for external APIs (fairness critical), fixed window for internal/trusted. Hybrid: Sliding window counter (approximation, lower memory than full log).

Choose based on use case: REST: Simple CRUD apps, public APIs, standard web apps, teams familiar with REST, caching important (CDN support). Widely supported, easy to debug (curl, Postman), good documentation (OpenAPI). GraphQL: UI-heavy apps (SaaS dashboards, e-commerce), mobile apps needing flexible queries, multiple client types, data from multiple sources, frequent requirement changes. Efficient data fetching, strong typing, great developer experience. gRPC: Internal microservices, performance-critical systems (<10ms latency), high throughput (>10k req/s), real-time streaming (IoT, chat, telemetry), polyglot services. 5-10x faster than REST. 2025 pattern: Hybrid architecture - REST for external/simple APIs, GraphQL for complex UIs, gRPC for internal services. Example: Netflix uses all three - gRPC for streaming, GraphQL for recommendations, REST for account. Don't: Force single choice - use right tool for each job.

Hybrid architecture combines multiple API technologies for different use cases within same system. Pattern: External clients → API Gateway (protocol translation) → REST/GraphQL (public) → gRPC (internal microservices). Benefits: (1) Right tool per job - REST (simplicity/caching), GraphQL (flexible queries), gRPC (performance/streaming). (2) Gradual adoption - start REST, add others incrementally. (3) Team optimization - 58% faster feature delivery with REST patterns, 43% mobile apps see 28-44% data reduction with GraphQL (2025 surveys). Examples: Netflix (gRPC video, GraphQL recommendations, REST accounts), Uber (gRPC internal, REST public), Shopify (GraphQL storefront, REST admin). Implementation: API Gateway with protocol adapters (gRPC-gateway, GraphQL federation), shared auth (JWT), unified monitoring. Components: Service layer (business logic), consistency layer (behavior across protocols), protocol adapters (entry points). 2025 reality: Most large systems hybrid, 12-18 month ROI over single-protocol.

Decision criteria: Choose REST when: (1) Simple CRUD, resource-based model fits, (2) Caching critical (CDN, browser HTTP caching), (3) Public API for external developers (predictable routes, stable contracts), (4) Team lacks GraphQL experience, (5) Banking/e-commerce (mature security patterns, stateless reliability). Choose GraphQL when: (1) Complex UI with varying data needs (dashboards, admin panels), (2) Multiple client types (web/iOS/Android) need different data shapes, (3) Heterogeneous clients, rapidly evolving UIs, (4) Over/under-fetching problems, (5) Mobile bandwidth matters (30% resource reduction for complex queries). 2025 adoption: 61% organizations use GraphQL (Postman), REST remains dominant for public APIs. Pattern: REST for core public resources, GraphQL for internal apps. Recommendation: Start REST for MVP (<10 endpoints, <3 clients), migrate when complexity justifies (typically >10 endpoints, >3 client types). Don't: Resume-driven development, measure pain points first.

Performance ranking (fastest to slowest): gRPC > REST > GraphQL (for same use case). gRPC: 5-10x faster than REST (binary protobuf, HTTP/2), 60% smaller payloads, 6x faster parsing, <10ms latency achievable. Use for: High throughput (>10k req/s), low latency (<10ms). REST: Good performance with caching, HTTP/1.1 overhead, JSON parsing slower than protobuf, easily cached (CDN, browser). Typical: 50-200ms latency. GraphQL: Can be faster than REST (fetch only needed data), but N+1 problem degrades performance 10-100x without DataLoader, caching harder (query-specific responses). With optimizations: Similar to REST. 2025 reality: gRPC for backend (speed), REST for external (caching), GraphQL for complex UIs (flexibility). Don't: Choose based on performance alone - developer experience, ecosystem, team expertise matter more for most apps. Measure before optimizing.

Migrate when: (1) Multiple endpoints per UI view (over-fetching), (2) Different clients need different data shapes, (3) API changes frequently for UI, (4) Mobile bandwidth critical (fetch only needed), (5) Developer velocity slowing (API-UI coupling). Don't migrate when: (1) REST works fine, (2) Simple CRUD, (3) Team lacks expertise/time, (4) Caching critical (HTTP caching simpler), (5) Stable API. Migration strategy: (1) Gradual - add GraphQL alongside REST, use feature flags (Slack routed 10% traffic initially), migrate clients incrementally. (2) Gateway - wrap REST with GraphQL schema (StepZen, Hasura), no backend changes. (3) Hybrid - new features GraphQL, legacy REST. Results: 25% reduction in backend round trips average, Netflix achieved 8x performance boost (10MB to 200KB payload). Cost: 2-6 months medium API, requires GraphQL expertise. 2025 reality: 60% teams use API monitoring to inform migration (Postman 2024). Most add GraphQL for new features, maintain REST. Measure pain points before migrating.