Browse Chunks

Accept-Version header versioning is an API versioning strategy where clients declare the desired API version through a custom HTTP header (commonly `Accept-Version` or `X-API-Version`) rather than embedding it in the URI. It addresses the pain point of evolving API contracts without breaking existing clients by allowing per-request version negotiation. This approach is triggered when designing REST APIs that need backward-compatible evolution while keeping resource URIs clean and stable.

client sends Accept-Version: <version> → server routes to version-specific handler

Subdomain versioning assigns independent version numbers to distinct subdomains within a larger system so each can evolve at its own pace. It addresses the pain point of monolithic release cycles where a stable, slow-changing core domain is blocked by rapidly evolving supporting or generic subdomains. Teams reach for it when bounded contexts or microservices need to release independently without coupling their change cadence.

assign version → scope to subdomain → publish compatibility contract → release on independent cadence

Idempotent endpoints are HTTP API endpoints that produce the same result regardless of how many times the same request is made, even when retries occur. They address the pain point of network failures causing clients to retry requests, which without idempotency would create duplicate side effects like double-charges or duplicate records. The trigger is designing any mutating endpoint that may be retried by clients, proxies, or message brokers in distributed systems.

design endpoint → ensure repeated identical requests yield same result → use idempotency keys for non-naturally-idempotent verbs

JSON:API is a specification that defines how clients should request and servers should deliver JSON-encoded resources over HTTP. It addresses the pain of inconsistent API response shapes and ad-hoc relationship handling by standardizing resource representation, relationships, and compound documents. Developers reach for it when designing or consuming REST APIs that need predictable, self-describing JSON payloads with built-in support for related resources.

define resource types → specify attributes and relationships → serialize with JSON:API document structure (data, included, links, meta)

GraphQL is a query language and server-side runtime for APIs that allows clients to request exactly the data they need and nothing more. It addresses the over-fetching and under-fetching problems common in REST APIs by giving clients control over the shape of responses. Developers reach for GraphQL when building APIs consumed by multiple clients with differing data needs or when network efficiency matters.

define schema → write resolvers → client sends query → server returns exactly requested fields

Stateless design structures components so each request or operation carries all the information it needs, with no reliance on prior server-side session memory. It eliminates the complexity of managing shared mutable state across concurrent users and removes the need to synchronize session data between nodes. You reach for it when scaling horizontally, building REST APIs, or designing systems that must tolerate node failures without data loss.

client sends self-contained request → server processes without prior context → response returned → no session stored

Resource-oriented architecture treats named, addressable resources as the primary abstraction for designing distributed systems, with each resource identified by a URI and manipulated through a uniform interface. It addresses the challenge of building scalable, evolvable APIs by making resources the unit of state and interaction rather than remote procedure calls. Developers reach for it when designing public APIs, web services, or any system where clients need to discover and manipulate entities across a network.

identify resources → assign identifiers → define representations → expose uniform operations

Endpoint naming conventions establish the rules for constructing URI paths in REST and HTTP APIs. They address the pain point of inconsistent or ambiguous endpoint design that makes APIs hard to learn, document, and evolve. They are triggered when designing a new API surface, reviewing existing endpoints for consistency, or generating client SDKs from a specification.

pluralized-noun resource paths with hierarchical sub-resources and consistent casing (kebab-case or camelCase)

Caching headers are HTTP response headers (Cache-Control, ETag, Last-Modified, Expires, Vary) that instruct browsers and intermediate proxies how to store, reuse, and revalidate fetched resources. They address the pain point of redundant network round-trips that waste bandwidth, inflate latency, and overload origin servers. Developers reach for them whenever serving static assets, public API responses, or any content whose freshness can be bounded in time.

set Cache-Control: <directive> on response → browser/proxy caches per directive → conditional revalidation via ETag or Last-Modified

An API gateway is a server that sits between clients and a collection of backend services, acting as a single entry point that routes requests, aggregates responses, and enforces cross-cutting concerns. It addresses the pain of clients having to know the topology of every internal service and the duplication of auth, rate limiting, and logging logic across services. Engineers reach for it whenever a system grows beyond a handful of services or needs to expose internal APIs to external consumers with consistent policy enforcement.

client → API gateway → backend services (with auth, rate limiting, routing, aggregation)

Webhooks are user-defined HTTP callbacks that one application sends to another when a specific event occurs, replacing the need for constant polling. They address the inefficiency and latency of polling APIs by pushing data the moment something happens. Developers reach for webhooks when integrating services that need real-time event notifications without maintaining persistent connections.

register endpoint URL → service POSTs event payload on trigger → receiver verifies signature and processes event

JWT authentication is a token-based mechanism where a server issues a cryptographically signed JSON Web Token after verifying credentials, and the client presents this token in subsequent requests to prove identity. It addresses the statelessness challenge in distributed systems by eliminating the need for server-side session storage. It is reached for when building APIs or microservices that require scalable, verifiable identity propagation across service boundaries.

client sends credentials → server verifies → server signs JWT → client stores token → client sends token in Authorization header → server verifies signature → request authenticated

The circuit breaker pattern wraps a remote call to detect repeated failures and short-circuit subsequent calls, preventing cascade failures in distributed systems. It addresses the pain point of hammering a failing dependency and exhausting resources while it is down. The trigger is any code path that calls an unreliable external service or resource where repeated failures should be contained rather than retried blindly.

wrap call → monitor failures → open circuit on threshold → fail fast → half-open to test recovery → close on success

Bulk operations group multiple individual actions into a single batch to reduce overhead from network round-trips, transaction commits, or repeated setup costs. They address the performance penalty of processing items one at a time when the underlying system can handle many at once. Developers reach for bulk operations when they need to insert, update, or process hundreds or thousands of records efficiently.

collect items into batch → execute single bulk operation → handle partial failures

Consumer-driven contracts (CDC) is a testing approach where consumers of an API define the exact request/response interactions and data shapes they depend on, and providers must satisfy those contracts before deploying. It addresses the pain point of silent breaking changes in microservices where providers evolve independently of multiple consumer teams. It is triggered when shared APIs are consumed by independent teams with separate release cadences and no full integration test environment.

consumer defines expected request/response → publishes contract to broker → provider verifies against contract → CI gates deployment

Backend for frontend (BFF) is an architectural pattern where each client type (web, mobile, desktop) gets its own dedicated backend service rather than sharing a single generic API. It addresses the pain point of forcing diverse clients with different needs to consume the same API surface, which leads to over-fetching, under-fetching, or excessive client-side aggregation logic. Teams reach for it when multiple client platforms need tailored data shapes, authentication flows, or aggregation strategies that diverge significantly.

client request → BFF layer aggregates from multiple backend services → reshapes response for that specific client

Health check endpoints are HTTP routes (commonly /health, /healthz, or /ready) that return a simple status response indicating whether a service is alive and able to handle requests. They address the pain point of orchestrators and load balancers needing a reliable, low-cost signal to decide whether to route traffic to or restart an instance. They are reached for whenever a service is deployed behind infrastructure that requires liveness and readiness probes.

expose HTTP route returning status → orchestrator polls periodically → instance marked healthy or unhealthy

A correlation ID is a unique identifier attached to a request as it flows through multiple services in a distributed system, allowing engineers to trace a single transaction across logs, metrics, and traces. It addresses the pain point of debugging failures that span service boundaries where individual log streams are disconnected. It is triggered when investigating incidents in microservices architectures or any system where one user action crosses multiple components.

generate unique ID → attach to request context → propagate via headers/logs → aggregate in observability backend

ETag headers are HTTP response headers that carry an opaque identifier representing a specific version of a resource. They solve the pain point of efficiently detecting whether a cached resource has changed without re-downloading the full payload. Developers reach for them when implementing conditional GET requests, cache validation, or optimistic concurrency control in REST APIs.

client sends conditional header → server checks ETag match → returns 304 Not Modified or 200 with new ETag

Optimistic concurrency control (OCC) is a strategy where concurrent transactions proceed without acquiring locks, then verify at commit time that no other transaction has modified the same data, typically using version numbers or timestamps. It addresses the throughput bottleneck that pessimistic locking creates in low-contention workloads where conflicts are rare. Triggered when designing systems with concurrent writers where blocking would be wasteful but data integrity must still be preserved.

read entity with version → modify locally → write with version check → retry on conflict

Schema-first design defines the data shape, API contract, or type definitions before writing any implementation logic. It addresses the pain point of contract drift, inconsistent data models, and integration bugs that surface late in development. It is triggered when building APIs, microservices, or data pipelines where multiple consumers and producers must agree on a shared structure.

define schema → generate types/validators → implement business logic against contract

Throttling caps the rate at which an operation, event, or request is allowed to proceed, enforcing a steady maximum throughput rather than a hard cutoff. It addresses the pain point of bursty workloads overwhelming downstream services, exhausting CPU/memory, or violating third-party API quotas. Developers reach for it whenever a producer can generate work faster than a consumer (or a contract) can safely handle it.

measure elapsed time since last execution → compare against minimum interval → invoke handler if interval elapsed, otherwise drop or defer

API composition is the practice of combining multiple API calls or service endpoints to produce a unified result or workflow. It addresses the need to build complex functionality from smaller, reusable service boundaries rather than monolithic operations. Engineers reach for it when a single API cannot fulfill a business requirement and multiple endpoints must be orchestrated into one coherent response.

call api_a → transform response → call api_b with derived input → aggregate results → return composed response

The Saga pattern manages data consistency across distributed services by sequencing local transactions, each paired with a compensating action that undoes its effect on failure. It addresses the impossibility of using traditional ACID transactions or two-phase commit across microservices with independent databases. Engineers reach for it when a business workflow spans multiple services and must remain reliable despite partial failures.

define saga steps → execute sequentially → invoke compensating action for each completed step on failure

Server-Sent Events (SSE) is a web standard that lets a server push real-time updates to a client over a single long-lived HTTP connection using the text/event-stream MIME type. It addresses the pain point of unidirectional server-to-client streaming without the overhead of WebSockets or the latency of repeated polling. The trigger is needing lightweight, one-way push delivery from server to browser through standard HTTP infrastructure.

client opens EventSource(url) → server sends text/event-stream chunks → client receives MessageEvent objects with auto-reconnect

Service mocking replaces real external services (databases, third-party APIs, message brokers) with programmable test doubles that simulate their behavior at the network or protocol boundary. It addresses the pain point of tests being slow, flaky, or impossible to run when code depends on services that are unavailable, slow, or have side effects in test environments. The trigger is writing tests for code that interacts with services you do not control or cannot reach reliably from CI.

define mock behavior → inject into system under test → exercise code → verify interactions

A service mesh is a dedicated infrastructure layer that handles service-to-service communication through sidecar proxies deployed alongside each service. It addresses the pain point of scattering cross-cutting concerns—retries, timeouts, mTLS, circuit breaking, observability—across every microservice codebase. The trigger is operating a microservices fleet large enough that embedding networking logic in application code becomes unmaintainable.

deploy sidecar proxies alongside services → configure traffic, security, and observability policies → observe and control inter-service communication

The Sidecar pattern deploys auxiliary components alongside a primary application in the same host or pod, sharing the same lifecycle and network namespace. It addresses the pain of cross-cutting concerns like logging, monitoring, and networking that would otherwise pollute application code or require per-language reimplementation. Engineers reach for it when a primary service needs supporting infrastructure without coupling that support to the application's codebase or language runtime.

deploy primary application + co-located helper service → share network namespace and lifecycle → offload cross-cutting concern

The Bulkhead pattern isolates critical resources into independent compartments so that a failure in one compartment cannot exhaust shared resources and bring down the entire system. It addresses cascading failures in distributed systems where one slow or failing dependency consumes all available threads, connections, or memory. Engineers reach for it when designing fault-tolerant services that must degrade gracefully under partial failure.

partition resource pool → assign compartment per dependency → isolate failures → degrade independently

The retry pattern automatically re-attempts a failed operation a configurable number of times before propagating the error to the caller. It addresses the pain point of transient failures (network blips, brief service unavailability, temporary resource contention) that would otherwise break user-facing flows. Developers reach for it when an operation is idempotent or safely repeatable and the cost of failing immediately exceeds the cost of waiting and trying again.

attempt operation → on transient failure → wait (with optional backoff) → retry up to max_attempts → escalate if exhausted

Token bucket is a rate-limiting algorithm that maintains a counter of tokens refilled at a steady rate up to a maximum capacity; each incoming request consumes one token and is rejected or delayed when the bucket is empty. It addresses the tension between enforcing an average rate limit and tolerating short bursts of traffic. Engineers reach for it whenever a downstream service must be protected from overload while still allowing legitimate spikes.

define capacity and refill rate → on each request, compute elapsed time and top up tokens → if tokens ≥ 1, decrement and allow; otherwise reject or queue

The Sunset HTTP header communicates a future date when an API endpoint or resource will be retired. It addresses the pain point of clients discovering endpoint removal only after a breaking change has already shipped. It is triggered when a maintainer knows the exact removal date of a deprecated endpoint and wants to give clients machine-readable advance notice.

Server emits `Sunset: <rfc1123-date>` response header → client parses date → schedules migration before that date

Contract testing verifies that two services can communicate by checking each side against a shared specification of expected interactions. It addresses the pain point where integration tests require running all services together, slowing CI and making failures hard to localize. You reach for it when a consumer and provider are owned by different teams or deployed independently and you need confidence that breaking API changes are caught early.

define expected request/response interactions → publish contract → consumer verifies mock matches contract → provider verifies real implementation satisfies contract

A schema registry is a centralized service that stores and manages data schemas (typically Avro, Protobuf, or JSON Schema) for use in event-driven systems. It addresses the pain point of coordinating schema versions across producers and consumers in distributed streaming pipelines where payloads must remain decodable across independent deployments. Engineers reach for it when building Kafka-based or similar streaming architectures where data contracts between services must be enforced and evolved safely.

register schema → assign schema ID → serialize payload with ID → consumer fetches schema by ID

Distributed tracing tracks a single request as it flows through multiple services in a distributed system, recording timing and causal relationships at each hop. It addresses the pain point of debugging latency or failures when a request crosses service boundaries where logs alone cannot reconstruct the full path. Engineers reach for it when a user-facing request fails or slows down and the root cause could lie in any of dozens of microservices.

instrument service entry → propagate trace context via headers → record spans for each operation → export traces to backend → query by trace ID for root cause analysis

OpenTelemetry is an open-source observability framework that provides vendor-neutral APIs, SDKs, and instrumentation for collecting traces, metrics, and logs from distributed applications. It addresses the pain point of fragmented telemetry tooling by unifying instrumentation across services and languages. Developers reach for it when they need to debug latency, correlate requests across microservices, or export telemetry to multiple backends without rewriting code.

instrument application → configure exporter → collect traces/metrics/logs → export to backend

Cache aside is a caching strategy where the application layer is responsible for reading from and populating the cache, while the underlying data store remains the source of truth. It addresses the pain point of reducing read latency and database load without coupling the data store to the cache or requiring the store to support cache invalidation natively. Developers reach for it when they need fast reads on hot data but cannot or do not want to modify the primary store to manage cache coherence itself.

read request → check cache → on miss, read from store → populate cache → return; write request → update store → invalidate cache entry

An idempotency key is a unique client-generated token attached to a mutating API request so that retries of the same request produce the same result instead of duplicating side effects. It addresses the pain point where network failures, timeouts, or client retries can cause a payment, order, or message to be processed multiple times. Engineers reach for it whenever a request is non-safe (POST/PUT/DELETE) and the operation has irreversible external side effects.

client generates unique key → attaches to mutating request → server stores key+result → retries with same key return cached result

Problem Details is a standardized format (RFC 7807, updated by RFC 9457) for HTTP error responses that conveys machine-readable error information using the application/problem+json or application/problem+xml media type. It addresses the pain point of inconsistent, opaque error payloads that force API clients to parse free-form strings or guess at error semantics. Developers reach for it whenever designing or consuming REST APIs that need structured, interoperable error reporting.

return response with Content-Type: application/problem+json and body { type, title, status, detail, instance }

JSON Patch (RFC 6902) is a JSON document format that describes a sequence of operations to apply to a target JSON document, transforming it into a new state. It addresses the problem of partially updating a resource without resending the entire payload, which saves bandwidth and avoids lost-update races on concurrent writes. Engineers reach for it when designing REST PATCH endpoints or when they need to express structured, atomic mutations over a network.

describe operations → apply patch to target document → produce updated document

CloudEvents is a CNCF specification that defines a common envelope format for describing event data across cloud platforms and services. It addresses the pain point of vendor lock-in and interoperability gaps when systems emit and consume events through different proprietary schemas. Developers reach for it when designing or integrating event-driven pipelines that must traverse multiple runtimes, brokers, or serverless platforms.

specversion + id + source + type + datacontenttype + time + data → JSON envelope

The Saga pattern manages data consistency across microservices by decomposing a distributed transaction into a sequence of local transactions, each paired with a compensating action that semantically reverses it. It addresses the impossibility of traditional ACID transactions spanning multiple services without distributed locks. Developers reach for it when a business operation must touch several services and atomicity cannot be guaranteed by a single database.

initiate saga → execute local transaction N → on success trigger N+1 → on failure invoke compensating transaction for completed steps → reach final consistent state

Event Sourcing is an architectural pattern that persists application state as an append-only sequence of immutable domain events rather than by mutating current state in place. It addresses the pain point of losing historical context, audit trails, and the ability to reason about how state evolved over time. It is reached for when the domain demands full change history, temporal queries, or the ability to reconstruct any past state deterministically.

capture domain event → append to immutable event store → derive current state by replaying events (optionally from snapshot)

CQRS is an architectural pattern that separates read operations (queries) from write operations (commands) into different models, handlers, or even data stores. It addresses the pain point that traditional CRUD systems couple read and write concerns, making it hard to scale, optimize, or evolve each path independently. Developers reach for it when read and write workloads have fundamentally different performance, consistency, or schema requirements.

define command model with invariants → route writes to command handler → emit domain events → project events into read model → route queries to read model