Executive Summary
API architecture in 2026 has evolved far beyond basic REST endpoints. While REST remains dominant at 70% adoption, event-driven architecture has reached 60%, gRPC 44%, GraphQL 48%, and CQRS 37%. Organizations are combining multiple patterns: REST for public APIs, gRPC for internal microservice communication, event-driven for async workflows, and CQRS for domains with asymmetric read/write loads. Resilience patterns (circuit breaker, bulkhead, retry with backoff) are standard practice in distributed systems.
- Event-driven architecture reached 60% adoption in 2026. Apache Kafka, RabbitMQ, and cloud-native event buses (EventBridge, Pub/Sub) enable loose coupling, eventual consistency, and horizontal scalability across microservices.
- CQRS adoption grew to 37% as organizations separate read and write models for domains with different access patterns. Combined with event sourcing, CQRS provides full audit trails and independent read/write scaling.
- Circuit breaker and bulkhead patterns are standard in microservices architectures. Resilience4j (Java), Polly (.NET), and service meshes (Istio, Linkerd) implement these patterns without application code changes.
- API gateways are essential infrastructure for microservices. Kong, AWS API Gateway, Traefik, and Envoy handle authentication, rate limiting, routing, and observability at the edge.
70%
REST API adoption
60%
Event-driven adoption
44%
gRPC adoption
37%
CQRS adoption
Part 1: API Styles Compared
The three dominant API styles in 2026 are REST, GraphQL, and gRPC, each optimized for different scenarios. REST uses HTTP methods and resource-oriented URLs, making it cacheable, widely understood, and ideal for public APIs. GraphQL provides a typed schema with client-specified queries, eliminating over-fetching and under-fetching, ideal for frontend-driven data needs. gRPC uses Protocol Buffers and HTTP/2 for high-performance, strongly-typed, streaming-capable communication between services.
REST strengths: HTTP caching (CDN, browser), wide tooling support, human-readable (JSON), stateless, and well-understood by developers. REST weaknesses: over-fetching (getting more fields than needed), under-fetching (multiple round trips for related data), and no standard for real-time updates. REST is the default choice for public APIs, webhook callbacks, and simple CRUD services.
gRPC strengths: binary serialization (smaller payloads, faster parsing), HTTP/2 multiplexing, bidirectional streaming, strong typing with code generation, and deadlines/cancellation propagation. gRPC weaknesses: not browser-native (requires gRPC-Web proxy), harder to debug (binary), less tooling for ad-hoc testing. gRPC is the default for internal microservice communication where performance matters.
API Architecture Adoption (2018-2026)
Source: OnlineTools4Free Research
Part 2: REST API Design
REST API design principles: use nouns for resources (/users, /orders), not verbs (/getUser). Use HTTP methods semantically: GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove). Use plural nouns (/users, not /user). Nest related resources (/users/123/orders). Use query parameters for filtering, sorting, and pagination (/users?role=admin&sort=name&page=2).
Response design: use consistent response envelopes. Success responses contain data and meta objects. Error responses contain error code, message, and details array. Include HATEOAS links for discoverability. Return appropriate HTTP status codes. Support content negotiation (Accept header). Provide pagination metadata (total, page, pageSize, nextCursor).
Idempotency: GET, PUT, DELETE are naturally idempotent. For POST operations that must not be duplicated (payments, orders), require an Idempotency-Key header. The server stores the response keyed by the idempotency key and returns the stored response for duplicate requests. Stripe, PayPal, and most payment APIs use this pattern. Implement with Redis or database storage with TTL.
Part 3: CQRS Pattern
CQRS separates the application into command side (writes) and query side (reads). The command side handles create, update, and delete operations using domain models and business rules. The query side serves read operations using denormalized views optimized for the specific queries. The two sides can use different databases: a relational database for writes (strong consistency, transactions) and Elasticsearch or Redis for reads (fast queries, flexible search).
Implementation: commands are validated, processed by domain logic, and persisted. Domain events are published to update the read model. The read model is eventually consistent with the write model. Synchronization can be: synchronous (in-process, simpler, slower writes), asynchronous via events (Kafka, RabbitMQ, faster writes, eventual consistency). The read model can be rebuilt from events at any time.
When to use CQRS: (1) Read and write patterns differ significantly (e.g., complex writes with business rules, simple reads with search). (2) Read and write loads differ (10x more reads than writes). (3) Different teams own reads and writes. (4) You need an audit trail (combine with event sourcing). (5) Domain complexity justifies the overhead. When NOT to use: simple CRUD, small applications, teams without distributed systems experience, or prototypes.
CQRS vs Traditional Architecture
6 rows
| Aspect | Traditional | CQRS | Tradeoff |
|---|---|---|---|
| Data Model | Single model for reads and writes. Same schema serves all operations. | Separate read model (optimized for queries) and write model (optimized for commands). Different schemas. | CQRS adds complexity but enables independent optimization of read and write paths. |
| Scalability | Scale the entire application together. Read-heavy workloads constrained by write model. | Scale reads and writes independently. Read replicas can use different storage (Elasticsearch, Redis). | CQRS enables 10-100x read scalability but requires managing model synchronization. |
| Consistency | Strong consistency by default. Single source of truth. | Eventual consistency between write and read models. Read model may lag behind writes. | Eventual consistency simplifies scaling but complicates UI (stale reads after writes). |
| Complexity | Simple to understand and maintain. One codebase, one database. | Higher complexity: two models, event synchronization, eventual consistency handling. | Only justified for complex domains with different read/write patterns. |
| Event Sourcing | Current state only. History lost unless explicitly logged. | Often combined with event sourcing: store events, derive state. Full audit trail. | Event sourcing provides perfect audit trail but increases storage and replay complexity. |
| Best For | CRUD applications, simple domains, small teams, rapid prototyping. | Complex domains, high-read workloads, event-driven architectures, audit requirements. | Most applications do not need CQRS. Start with traditional; migrate when needed. |
Part 4: Event Sourcing
Event sourcing stores all state changes as an immutable sequence of events. Instead of updating a database row (UPDATE orders SET status = 'paid' WHERE id = 123), you append an event (OrderPaid with orderId 123, amount 49.99, and timestamp). The current state is derived by replaying all events for an entity. This provides a complete audit trail, the ability to query state at any point in time, and the ability to replay events to rebuild projections or fix bugs.
Event store design: events are immutable (append-only), ordered per aggregate, and contain all data needed to reconstruct state. Each event has: aggregate ID, event type, event data (payload), timestamp, and version number. Snapshots periodically save the current state to avoid replaying millions of events. Event schema evolution requires careful versioning: upcasting (transforming old events to new schema), weak schema (tolerant reader), or versioned event types.
Challenges: (1) Event schema evolution is hard (events are immutable, schemas change). (2) Querying current state requires replaying events or maintaining projections. (3) Eventual consistency between write model and projections. (4) Increased storage (every state change is stored). (5) Debugging requires understanding event sequences. (6) Not suitable for simple CRUD applications. Tools: EventStoreDB, Axon Framework (Java), Marten (.NET), custom implementations with Kafka/PostgreSQL.
Part 5: Saga Pattern
The saga pattern manages distributed transactions that span multiple microservices. A traditional distributed transaction (two-phase commit) requires all participants to lock resources and coordinate, which is slow and reduces availability. A saga breaks the operation into a sequence of local transactions, each with a compensating action that undoes its effect if a later step fails.
Choreography sagas: each service emits an event after its local transaction, and the next service reacts to that event. No central coordinator. Example: OrderService creates order and emits OrderCreated. InventoryService reserves items and emits InventoryReserved. PaymentService charges card and emits PaymentProcessed. If payment fails, PaymentService emits PaymentFailed, InventoryService releases items. Pros: decoupled, simple for few steps. Cons: hard to track flow, circular dependencies, debugging is difficult.
Orchestration sagas: a central coordinator (orchestrator) manages the saga flow. The orchestrator sends commands to each service and handles responses. Example: SagaOrchestrator commands InventoryService to reserve, waits for response, commands PaymentService to charge, waits for response. If any step fails, the orchestrator sends compensating commands. Tools: Temporal (durable execution), AWS Step Functions (serverless), Axon Framework, MassTransit. Pros: clear flow, easier debugging, centralized error handling. Cons: single point of failure, coordinator complexity.
Part 6: API Gateway
An API gateway is the single entry point for all client requests to a microservices backend. It handles cross-cutting concerns: request routing (direct requests to the correct service), authentication and authorization (validate tokens, enforce policies), rate limiting (protect services from abuse), request/response transformation (aggregate responses, transform formats), caching (reduce backend load), load balancing (distribute traffic), and observability (logging, tracing, metrics).
Gateway patterns: (1) Routing gateway: simple request routing based on URL path or header. (2) Aggregation gateway: combine responses from multiple services into a single response (BFF pattern). (3) Offloading gateway: handle cross-cutting concerns (auth, rate limiting, SSL) to reduce service complexity. (4) Protocol translation: translate between protocols (REST to gRPC, HTTP to WebSocket). Most gateways combine all four patterns.
API Gateway Comparison (2026)
6 rows
| Gateway | Type | Protocol | Authentication | Best For |
|---|---|---|---|---|
| Kong | Open Source / Enterprise | REST, GraphQL, gRPC | JWT, OAuth2, OIDC, API Key | Large-scale API management, plugin ecosystem |
| AWS API Gateway | Managed (AWS) | REST, WebSocket, HTTP | IAM, Cognito, Lambda authorizer | AWS-native architectures, serverless backends |
| Envoy Proxy | Open Source (CNCF) | HTTP/2, gRPC, TCP | JWT, ext_authz | Service mesh (Istio), gRPC-heavy architectures |
| Traefik | Open Source / Enterprise | HTTP, TCP, UDP | BasicAuth, ForwardAuth | Docker/K8s environments, auto-discovery |
| NGINX | Open Source / NGINX Plus | HTTP, TCP, UDP, gRPC | JWT (Plus), basic, subrequest | High-performance reverse proxy, static serving |
| Apigee (Google) | Managed (GCP) | REST, GraphQL | OAuth2, API Key, SAML | Enterprise API management, monetization |
Part 7: Resilience Patterns
Distributed systems fail. Networks partition, services crash, databases slow down. Resilience patterns ensure the system degrades gracefully rather than cascading failures. The core patterns are: circuit breaker (stop calling failing services), bulkhead (isolate resource pools), retry with backoff (handle transient failures), timeout (prevent indefinite waiting), and fallback (provide degraded responses).
Circuit breaker in depth: monitor the failure rate of calls to a downstream service. In the Closed state, all requests pass through. When the failure rate exceeds a threshold (e.g., 50% of the last 20 calls), the circuit trips to Open: all requests fail immediately with a fallback response, without making the downstream call. After a configurable timeout (e.g., 30 seconds), the circuit enters Half-Open: one trial request is allowed. If it succeeds, the circuit closes; if it fails, it remains open for another timeout period.
Combining patterns: apply retry with backoff for transient failures, wrap with a circuit breaker to prevent retrying a dead service, use bulkhead to isolate the failure, and provide a fallback for degraded functionality. Example: payment service call with 3 retries (exponential backoff), circuit breaker (trip at 50% failure, 30s timeout), semaphore bulkhead (max 10 concurrent calls), fallback (queue payment for later processing).
Resilience Patterns Reference
8 rows
| Pattern | Category | Description | Tools |
|---|---|---|---|
| Circuit Breaker | Fault Tolerance | Monitor downstream service calls and trip (open) the circuit when failures exceed a threshold. Requests fail fast without calling the downstream. After a timeout, allow a trial request (half-open). If it succeeds, close the circuit. | Resilience4j, Polly, Hystrix (deprecated), Envoy |
| Bulkhead | Isolation | Isolate resources (thread pools, connection pools, semaphores) per downstream service. If one service exhausts its pool, other services are unaffected. Named after ship bulkheads that prevent flooding from spreading. | Resilience4j, Polly, Envoy, Istio |
| Retry with Backoff | Fault Tolerance | Retry failed requests with increasing delays (exponential backoff + jitter). Handles transient failures: network glitches, temporary overloads, DNS resolution delays. Cap retries (3-5) and add jitter to prevent thundering herd. | axios-retry, Resilience4j, Polly, Tenacity |
| Rate Limiting | Protection | Limit the number of requests a client can make in a time window. Algorithms: token bucket (smooth), sliding window (precise), fixed window (simple), leaky bucket (steady output). Return HTTP 429 Too Many Requests when exceeded. | Kong, API Gateway, NGINX, Redis-based |
| Timeout | Fault Tolerance | Set maximum time to wait for a response. Prevents threads from blocking indefinitely. Use aggressive timeouts (1-5s for APIs) and circuit breakers together. Different timeout values for connect vs read operations. | HTTP clients, Envoy, Istio, service mesh |
| Fallback | Degradation | Provide a degraded response when the primary service fails. Return cached data, default values, or redirect to an alternative service. Graceful degradation preserves partial functionality during outages. | Resilience4j, Polly, custom code |
| Saga | Distributed Transactions | Manage distributed transactions across services using a sequence of local transactions with compensating actions. If step 3 fails, run compensating actions for steps 2 and 1. Two types: choreography (events) and orchestration (central coordinator). | Temporal, Axon Framework, MassTransit, custom |
| Strangler Fig | Migration | Gradually replace a legacy system by routing requests to new services one endpoint at a time. The new system grows around the old one like a strangler fig tree. No big-bang migration; gradual, reversible transition. | API gateway routing, feature flags, NGINX |
Part 8: Versioning and Evolution
API evolution is inevitable. The goal is to make changes without breaking existing clients. Non-breaking changes (additive): adding new fields, adding new endpoints, adding optional parameters. These do not require versioning. Breaking changes: removing fields, changing field types, renaming fields, removing endpoints, changing authentication. These require a new API version.
Versioning strategies: URL path (/v1/users, /v2/users) is the most common and explicit. Header versioning (X-API-Version: 2) keeps URLs clean but is less visible. Content negotiation (Accept: application/vnd.myapi.v2+json) is RESTful but complex. Best practice: use URL path versioning for simplicity, support at least N-1 version, announce deprecation with Sunset header, and provide migration guides.
API-first design: design the API contract (OpenAPI specification) before writing code. Benefits: frontend and backend teams can work in parallel, clear documentation exists before implementation, code can be generated from the spec, and contract tests verify the implementation matches the spec. Tools: Stoplight Studio, SwaggerHub, Postman. The OpenAPI spec is the single source of truth.
Part 9: API Security
API security is multi-layered: transport security (HTTPS, TLS 1.3), authentication (verifying identity), authorization (verifying permissions), input validation (preventing injection), rate limiting (preventing abuse), and monitoring (detecting attacks). Each layer addresses different threats. Security must be designed in from the start, not bolted on later.
Authentication patterns: OAuth 2.0 with Authorization Code + PKCE for user-facing applications (web, mobile). API keys for server-to-server and public APIs (simpler but weaker). JWT (JSON Web Tokens) for stateless authentication (verify signature without database lookup, but cannot be revoked). mTLS (mutual TLS) for internal service-to-service authentication in microservices. API keys should always be sent in headers (not URLs), rotated regularly, and scoped to specific permissions.
Authorization: RBAC (role-based access control) assigns permissions to roles (admin, editor, viewer). ABAC (attribute-based access control) evaluates policies based on attributes (user department, resource owner, time of day). Always check authorization at every endpoint, not just at the gateway. Use the principle of least privilege. Log all access attempts. Return 403 Forbidden for authorization failures (not 404, which leaks resource existence).
Part 10: HTTP Status Codes Reference
Correct HTTP status code usage is fundamental to REST API design. Status codes communicate the outcome of a request without requiring the client to parse the response body. Use the most specific code available: 201 Created (not 200) for resource creation, 204 No Content (not 200) for successful deletion, 409 Conflict (not 400) for duplicate creation, and 422 Unprocessable Entity (not 400) for business rule violations.
HTTP Status Codes Reference
14 rows
| Status Code | Category | Description | Use Case |
|---|---|---|---|
| 200 OK | Success | Request succeeded. Response body contains the requested resource. | GET resource, PUT update, general success |
| 201 Created | Success | Resource created successfully. Location header should contain URL of new resource. | POST creating new resource |
| 204 No Content | Success | Request succeeded but no response body. Used for operations that do not return data. | DELETE resource, PUT update with no body |
| 400 Bad Request | Client Error | Malformed request syntax, invalid parameters, or missing required fields. | Validation errors, missing fields, invalid JSON |
| 401 Unauthorized | Client Error | Authentication required or credentials are invalid. Misleading name: should be "Unauthenticated". | Missing or expired token, invalid credentials |
| 403 Forbidden | Client Error | Authenticated but not authorized for this resource or action. | Insufficient permissions, role-based access denial |
| 404 Not Found | Client Error | Resource does not exist at the requested URL. | Non-existent resource, deleted resource |
| 409 Conflict | Client Error | Request conflicts with current state. Often used for duplicate creation or version conflicts. | Duplicate email, optimistic locking conflict |
| 422 Unprocessable Entity | Client Error | Request is syntactically correct but semantically invalid. Business rule violation. | Insufficient balance, invalid state transition |
| 429 Too Many Requests | Client Error | Rate limit exceeded. Include Retry-After header to indicate when to retry. | API rate limiting, throttling |
| 500 Internal Server Error | Server Error | Unexpected server error. Do not expose internal details to clients. | Unhandled exception, database error |
| 502 Bad Gateway | Server Error | Gateway received invalid response from upstream service. | Upstream service crashed or returned invalid data |
| 503 Service Unavailable | Server Error | Service temporarily unavailable. Include Retry-After header. | Maintenance, overloaded, dependency down |
| 504 Gateway Timeout | Server Error | Gateway timed out waiting for upstream service response. | Slow upstream, network partition |
Part 11: Best Practices
Design: (1) Use API-first design with OpenAPI specs. (2) Design for the consumer, not the database schema. (3) Use consistent naming conventions (camelCase or snake_case, not mixed). (4) Implement pagination for all list endpoints. (5) Support filtering, sorting, and field selection. (6) Use idempotency keys for non-idempotent operations. (7) Document every endpoint with examples.
Reliability: (1) Implement circuit breakers for all downstream calls. (2) Use bulkheads to isolate failure domains. (3) Set aggressive timeouts (1-5 seconds for API calls). (4) Retry with exponential backoff and jitter. (5) Provide fallback responses. (6) Use health check endpoints (/health, /ready). (7) Implement graceful shutdown (drain connections before stopping).
Operations: (1) Log all requests with correlation IDs. (2) Monitor latency, error rate, and throughput (RED metrics). (3) Set up alerts for SLO violations. (4) Use distributed tracing (OpenTelemetry). (5) Version your API and support deprecation. (6) Rate limit per client and per endpoint. (7) Generate client SDKs from OpenAPI specs.
API Style Adoption (2024-2026)
Source: OnlineTools4Free Research
Glossary (41 Terms)
REST (Representational State Transfer)
ArchitectureAn architectural style for APIs based on HTTP methods (GET, POST, PUT, DELETE), resource URIs, statelessness, and content negotiation. RESTful APIs use standard HTTP semantics: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes. Resources are identified by URLs and represented as JSON. REST is the most widely adopted API style at 70% in 2026.
GraphQL
ArchitectureA query language for APIs that allows clients to request exactly the data they need. Single endpoint, typed schema, client-specified queries, real-time subscriptions. Eliminates over-fetching (getting more data than needed) and under-fetching (multiple round trips). Created by Facebook. Tools: Apollo, Relay, Hasura, GraphQL Yoga.
gRPC
ArchitectureA high-performance RPC framework using Protocol Buffers (protobuf) for serialization and HTTP/2 for transport. Features: bidirectional streaming, strong typing, code generation for 11+ languages, and smaller payloads than JSON. Used for: internal microservice communication, mobile backends, and performance-critical APIs.
CQRS (Command Query Responsibility Segregation)
PatternA pattern that separates read (query) and write (command) operations into different models. The write model handles commands (create, update, delete) and the read model is optimized for queries. Read and write models can use different databases and scale independently. Adds complexity but enables optimization for different access patterns.
Event Sourcing
PatternA pattern that stores state changes as a sequence of events rather than current state. The current state is derived by replaying events. Benefits: full audit trail, temporal queries (state at any point in time), event replay for debugging, and natural fit with CQRS. Challenges: event schema evolution, snapshot management, and increased storage.
Saga Pattern
PatternA pattern for managing distributed transactions across multiple services. A saga is a sequence of local transactions, each with a compensating action. If step N fails, compensating actions for steps N-1 to 1 are executed. Two types: choreography (services emit events) and orchestration (central coordinator manages the flow).
Circuit Breaker
ResilienceA resilience pattern that monitors downstream service calls and prevents cascading failures. Three states: Closed (requests pass through), Open (requests fail immediately), Half-Open (trial request to test recovery). Trips when failure rate exceeds a threshold. Prevents overwhelming a failing service and allows it time to recover.
Bulkhead Pattern
ResilienceA resilience pattern that isolates resources per downstream service or call type. Uses separate thread pools, connection pools, or semaphores. If one downstream service is slow and exhausts its pool, other services are unaffected. Named after ship bulkheads that prevent flooding from spreading across compartments.
API Gateway
InfrastructureA server that acts as the single entry point for API requests. Handles: request routing, authentication, rate limiting, load balancing, request/response transformation, caching, monitoring, and SSL termination. Examples: Kong, AWS API Gateway, Traefik, Envoy, NGINX. Essential for microservices architectures.
Rate Limiting
ProtectionControlling the number of requests a client can make in a time window. Algorithms: token bucket (allows burst, smooth average), sliding window log (precise, memory-heavy), fixed window (simple, boundary spike issue), leaky bucket (smooth output). Return HTTP 429 with Retry-After header. Implement at API gateway or application level.
Idempotency
Design PrincipleAn operation that produces the same result regardless of how many times it is executed. GET, PUT, DELETE are idempotent by design. POST is not idempotent. For non-idempotent operations, use idempotency keys: the client sends a unique key with the request, and the server returns the same response for duplicate keys. Prevents duplicate charges, orders, etc.
HATEOAS
RESTHypermedia As The Engine Of Application State. A REST constraint where API responses include hyperlinks to related actions and resources. Clients discover available actions from response links rather than hardcoding URLs. Example: an order response includes links to cancel, pay, and track. Rarely implemented fully in practice.
OpenAPI (Swagger)
DocumentationA specification for describing RESTful APIs. Defines endpoints, parameters, request/response bodies, authentication, and examples in YAML or JSON. Tools: Swagger UI (interactive documentation), Swagger Codegen (client/server generation), OpenAPI Generator, Redoc. OpenAPI 3.1 aligns with JSON Schema. The standard for API documentation.
API Versioning
Design PrincipleStrategies for evolving APIs without breaking existing clients. Approaches: URL path (/v1/users), query parameter (?version=1), custom header (X-API-Version: 1), content negotiation (Accept: application/vnd.api+json;version=1). Best practice: version at the URL path level for simplicity. Support at least N-1 version. Deprecate with Sunset header.
Pagination
Design PrincipleBreaking large result sets into pages. Strategies: offset-based (page=2&limit=20, simple but inconsistent with concurrent writes), cursor-based (after=cursor123, consistent, used by Facebook/Twitter), keyset-based (where id > 100 limit 20, fast with indexed columns). Include total count, next/previous links. Default page size: 20-100 items.
Content Negotiation
HTTPHTTP mechanism for selecting the response format. The client sends Accept: application/json or Accept: text/xml, and the server responds in the requested format. Also used for: language (Accept-Language), encoding (Accept-Encoding), and API versioning (vendor media types).
Webhook
IntegrationA mechanism where a server pushes notifications to a client URL when events occur. The client registers a callback URL; the server sends HTTP POST requests to that URL. Used for: payment confirmations (Stripe), CI/CD triggers (GitHub), messaging (Slack). Must handle: retries, signature verification, idempotency, and ordering.
WebSocket
ProtocolA full-duplex communication protocol over a single TCP connection. Enables real-time, bidirectional data flow between client and server. Used for: chat applications, live dashboards, collaborative editing, gaming. Starts as HTTP upgrade request (Upgrade: websocket). Alternatives: Server-Sent Events (SSE) for server-to-client only, which is simpler.
Server-Sent Events (SSE)
ProtocolA server-push technology where the server sends events to the client over a single HTTP connection. Simpler than WebSocket: uses standard HTTP, automatic reconnection, event IDs for resuming. One-directional (server to client). Used for: live feeds, notifications, progress updates. EventSource API in browsers.
Protocol Buffers (Protobuf)
SerializationA language-neutral, platform-neutral serialization format by Google. Defines message schemas in .proto files, generates code for 11+ languages. Binary format: smaller and faster than JSON. Used with gRPC. Supports schema evolution (field numbers). Alternative: FlatBuffers (zero-copy), MessagePack (JSON-compatible binary), Avro (schema registry).
API Contract
Design PrincipleThe formal agreement between API provider and consumer defining: endpoints, request/response schemas, error formats, authentication, rate limits, and SLAs. Documented with OpenAPI. Tested with contract testing (Pact). Changes to the contract require versioning. Breaking changes: removing fields, changing types, removing endpoints.
Backend for Frontend (BFF)
PatternA pattern where each frontend (web, mobile, desktop) has its own dedicated backend API. The BFF aggregates data from multiple microservices and tailors responses to the frontend needs. Prevents generic APIs that either over-fetch or under-fetch for different clients. Common in microservices architectures.
API Composition
PatternA pattern for implementing queries that span multiple microservices. An API composer invokes multiple services and combines their responses. Simpler than CQRS for read-heavy scenarios. Example: a product detail page calls product service, pricing service, and review service, then merges results. Risk: availability depends on all services being up.
Event-Driven Architecture (EDA)
ArchitectureAn architecture where services communicate by producing and consuming events through a message broker. Events represent state changes (OrderCreated, PaymentProcessed). Benefits: loose coupling, eventual consistency, scalability. Tools: Apache Kafka, RabbitMQ, AWS EventBridge, NATS. Challenges: event ordering, exactly-once delivery, debugging distributed flows.
Dead Letter Queue (DLQ)
MessagingA queue that stores messages that could not be processed after multiple retries. Prevents poison messages from blocking the main queue. Messages in the DLQ can be inspected, fixed, and replayed. Every message consumer should have a DLQ policy. Part of reliable message processing.
Optimistic Locking
ConcurrencyA concurrency control strategy where reads do not lock resources. Each resource has a version number or ETag. On update, the client sends the version; the server rejects the update if the version has changed (HTTP 409 Conflict). The client retries with the latest version. Lower contention than pessimistic locking but requires conflict handling.
OAuth 2.0
SecurityAn authorization framework for granting limited API access. Grant types: Authorization Code (web apps), PKCE (SPAs/mobile), Client Credentials (service-to-service), Device Code (TVs, CLIs). Tokens: access token (short-lived, used for API calls), refresh token (long-lived, used to get new access tokens). Standard for API authorization.
JSON Web Token (JWT)
SecurityA compact, URL-safe token format containing claims (payload) signed with HMAC or RSA/ECDSA. Three parts: header (algorithm), payload (claims like sub, exp, iat), signature. Stateless authentication: the server verifies the signature without database lookup. Risks: large tokens, cannot be revoked (unless using a blocklist), sensitive data should not be stored in the payload.
API Key
SecurityA simple authentication mechanism using a string token passed in a header (X-API-Key) or query parameter. Identifies the calling application, not the user. Used for: public APIs, rate limiting per client, usage tracking. Weaker than OAuth 2.0: no scopes, no expiration by default, shared secret. Always send over HTTPS.
Exponential Backoff
ResilienceA retry strategy that increases the delay between retries exponentially (1s, 2s, 4s, 8s, 16s). Combined with jitter (random offset) to prevent thundering herd. Formula: delay = min(cap, base * 2^attempt) + random(0, jitter). Standard for cloud API retries. AWS, Google Cloud, and Azure SDKs implement this by default.
Service Mesh
InfrastructureAn infrastructure layer for managing service-to-service communication in microservices. Provides: mTLS (mutual TLS), traffic management, observability, and resilience (retries, circuit breaking) without changing application code. Implementations: Istio (Envoy-based), Linkerd (lightweight), Consul Connect. Deployed as sidecar proxies alongside each service.
Correlation ID
ObservabilityA unique identifier passed through all services in a request chain. Enables tracing a request across microservices in logs and monitoring. Generated at the API gateway or first service. Passed via HTTP header (X-Correlation-ID, X-Request-ID). Essential for debugging distributed systems.
Health Check Endpoint
OperationsA dedicated API endpoint (/health, /healthz, /ready) that reports the service health status. Liveness: is the process running? Readiness: can it handle traffic? (checks database connectivity, downstream services). Used by load balancers and orchestrators for routing and restart decisions. Return 200 for healthy, 503 for unhealthy.
API Throttling
ProtectionLimiting the rate of API requests to prevent overload. Different from rate limiting (which returns 429): throttling may queue or slow down excess requests rather than rejecting them. Strategies: request queuing, priority queuing (premium clients first), adaptive throttling (based on server load). Implemented at API gateway or load balancer.
Event Storming
DesignA collaborative workshop technique for exploring complex business domains. Participants place sticky notes on a wall: orange (domain events), blue (commands), yellow (aggregates), pink (external systems), red (hot spots/questions). Used to discover bounded contexts, aggregates, and event flows. Inputs for CQRS, event sourcing, and microservice boundaries.
Bounded Context
DesignA DDD (Domain-Driven Design) concept that defines the boundary within which a particular model applies. Each bounded context has its own ubiquitous language and data model. Different contexts may use the same word with different meanings (e.g., "product" in catalog vs. inventory). Microservice boundaries often align with bounded contexts.
Aggregate
DesignA DDD concept: a cluster of domain objects treated as a single unit for data changes. The aggregate root is the entry point for all modifications. Aggregates enforce business invariants and consistency boundaries. Example: an Order aggregate contains OrderItems; all modifications go through the Order root. Events are emitted per aggregate.
Anti-Corruption Layer
PatternA DDD pattern that translates between a legacy system model and a new system model. Prevents the legacy model from "corrupting" the new domain model. Implemented as an adapter that maps between the two models. Used during: monolith-to-microservices migration, third-party integration, and bounded context integration.
API-First Design
PracticeAn approach where the API contract (OpenAPI spec) is designed and agreed upon before implementation begins. Benefits: parallel frontend/backend development, clear documentation, code generation, and contract testing. Tools: Stoplight, SwaggerHub, Postman. The API spec is the single source of truth for the interface.
Eventual Consistency
Distributed SystemsA consistency model where updates propagate asynchronously and the system converges to a consistent state over time. In CQRS: the read model may lag behind the write model. In event-driven systems: downstream services process events asynchronously. UI strategies: optimistic updates (show expected state immediately), polling, or real-time notifications.
Choreography vs Orchestration
PatternTwo approaches for coordinating multi-service workflows. Choreography: services emit and react to events autonomously (decentralized, loosely coupled, harder to track). Orchestration: a central coordinator directs the workflow (centralized, easier to track, single point of failure). Tools: Temporal and AWS Step Functions (orchestration), Kafka and EventBridge (choreography).
FAQ (15 Questions)
Raw Data Downloads
Citations and Sources
Try These Tools for Free
Put this knowledge into practice with our browser-based tools. No signup needed.
API Tester
Test REST APIs with GET, POST, PUT, DELETE, PATCH. Custom headers, body, response viewer, and session history.
JSON Formatter
Format, validate, and beautify JSON data with syntax highlighting.
JSON Editor
Visual JSON tree editor with add/remove keys, type changes, search, undo/redo, and import/export.
UUID Generator
Generate unique UUIDs (v1, v4, v7) for your applications.
URL Encoder
Encode and decode URLs instantly. Handle special characters, unicode, query strings. Free online tool.
Related Research Reports
The Complete Guide to Web APIs: REST, GraphQL, gRPC & Beyond (2026)
The definitive guide to web APIs in 2026. Deep dives into REST, GraphQL, gRPC, WebSocket, and webhooks. Covers authentication (OAuth 2.0, JWT), rate limiting, API design, security (OWASP Top 10), testing, and documentation. 27,000+ words with comparison charts and embedded tools.
GraphQL Complete Guide 2026: Schema, Resolvers, Subscriptions, Apollo, Relay, Security
The definitive GraphQL guide for 2026. Schema design, resolvers, subscriptions, Apollo, Relay, federation, caching, and security. 40 glossary, 15 FAQ. 30,000+ words.
Microservices Architecture Guide 2026: Monolith vs Microservices, Service Mesh, CQRS, Saga
The definitive microservices guide for 2026. Monolith vs microservices, modular monolith, service mesh, event-driven, CQRS, saga, DDD. 41 glossary, 15 FAQ. 30,000+ words.