JobCannon
All skills

API Design Patterns

Designing clean, consistent, and developer-friendly APIs

⬢ TIER 2Tech
High
Salary impact
9 months
Time to learn
Medium
Difficulty
12
Careers
AT A GLANCE

Senior backend/architect skill covering BFF pattern, API gateway architecture, idempotency keys, CQRS over APIs, async patterns (webhooks vs polling vs SSE), schema evolution, and saga choreography. Foundation for +$25k–$40k salary increase. 6–12 months to proficiency; 18 months to mastery of multi-service orchestration.

What is API Design Patterns

API Design Patterns are proven architectures and practices for building APIs that developers love to use: RESTful conventions (HTTP verbs, status codes), BFF (Backend-for-Frontend) pattern, API gateway architecture, idempotency for safe retries, CQRS (Command Query Responsibility Segregation) for splitting reads and writes, async patterns (webhooks vs. polling vs. SSE), schema evolution without breaking clients, rate limiting strategies, and saga choreography for distributed transactions. Unlike basic REST API building (which most developers learn), patterns address production complexity: scaling, resilience, backward compatibility, and multi-service coordination. A junior backend builds an API that works; a senior architect builds APIs that scale to 1M+ QPS, handle partial failures gracefully, and don't break clients for 5 years. API Design Patterns is the bridge between monolith development and distributed systems; it's where system design meets implementation. Master this skill, and you can architect the communication layer for any system.

🔧 TOOLS & ECOSYSTEM
KongApigeeTykAWS API GatewayEnvoyIstioAsyncAPIAWS EventBridgeApache KafkaPostmanReadMeSpectral

💰 Salary by region

RegionJuniorMidSenior
USA$125k$160k$220k
UK£70k£95k£140k
EU€75k€105k€150k
CANADAC$130kC$170kC$235k

❓ FAQ

BFF (Backend for Frontend) vs API Gateway — are they the same?
No. BFF is a lightweight aggregator service that shapes data for a specific client (web, mobile, TV). API Gateway is the entry point enforcing rate limiting, auth, versioning, logging. Modern architecture: client → API Gateway → BFF → microservices. A single BFF talks to 5–10 backend services; API Gateway sits in front of all BFFs.
How do I implement idempotency keys for safe retries?
Client generates a UUID (idempotency key). Server stores {key → response} in cache (Redis, Memcached) for 24 hours. On duplicate request, return cached response instead of re-executing. Implement as middleware; decorate all mutation endpoints (POST, PUT, DELETE). Critical for payments, refunds, and account changes.
Polling vs webhooks vs SSE vs WebSocket — which pattern for what?
Polling: client asks every N seconds (cheapest for sparse data, ~30s+). Webhooks: server POSTs to client on event (fire-and-forget, idempotency required, backoff needed). SSE: one-way server→client stream over HTTP (good for live updates, auto-reconnect). WebSocket: bidirectional, stateful (real-time chat, multiplayer games). For notifications: webhooks. For feeds: SSE. For two-way: WebSocket. For batch jobs: polling.
CQRS over APIs — separate read and write endpoints?
Yes. /api/v1/users/{id} (read) lives on a read replica or cache. /api/v1/users/{id}/update (write) hits primary DB + event bus. Allows different scaling, caching, and retry strategies per operation. Not required for small systems; essential for >1M QPS.
Schema evolution without breaking clients — how?
Add-only: new optional fields never break old clients. Deprecation headers: `Deprecation: true`, `Sunset: 2026-12-31T00:00:00Z`. Versioning: /v2/ endpoint runs in parallel for 6 months. Coexist strategies: clients read extra fields without error, ignore unknown fields. Always default missing fields on read, never require.
Saga pattern for distributed transactions — orchestration vs choreography?
Orchestration: central service (saga coordinator) calls services A→B→C, compensates on failure. Choreography: services publish events; downstream services listen and act, compensate by publishing reverse events. Orchestration is easier to debug. Choreography scales better and is loosely coupled. For <5 services: orchestration. For >10 with independent teams: choreography.
API rate limiting — fixed window vs sliding window vs token bucket?
Fixed window (simplest): reset counts every minute (fairness issues at boundaries). Sliding window: track requests in a time window (expensive). Token bucket (recommended): refill N tokens/minute, burst allowed. For public APIs: token bucket at gateway level + per-user quotas at service level. IETF draft-6585: `RateLimit-Limit: 100`, `RateLimit-Remaining: 45`, `RateLimit-Reset: 1640995200`.

Not sure this skill is for you?

Take a 10-min Career Match — we'll suggest the right tracks.

Find my best-fit skills →

Find your ideal career path

Skill-based matching across 2,536 careers. Free, ~10 minutes.

Take Career Match — free →