Browse Chunks

Pagination is a technique for dividing large datasets into discrete pages so clients can retrieve subsets incrementally rather than loading everything at once. It addresses the pain point of timeouts, memory exhaustion, and poor UX when an API or query returns more rows than can be efficiently transmitted or rendered in a single response. It is triggered whenever a result set is large enough that a single response would degrade performance or exceed practical limits.

client requests page or cursor → server returns subset plus next token → client repeats until exhausted

Content negotiation is the HTTP mechanism where client and server agree on the best representation of a resource based on request headers. It solves the problem of serving multiple formats, languages, or encodings from a single endpoint without requiring separate URLs for each variant. Triggered when an API must support diverse clients with different content, language, or encoding preferences.

client sends Accept-* headers → server selects best match → returns chosen representation with matching Content-Type

An idempotency key is a client-generated unique identifier attached to a mutating API request so the server can recognize and discard duplicate retries of the same operation. It addresses the pain point where network failures, timeouts, or client retries can cause the same action (e.g., a payment charge) to execute multiple times. Developers reach for it whenever a request is non-safe and a retry could produce duplicate side effects.

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

Conditional GET is an HTTP request pattern where the client includes validators such as If-None-Match or If-Modified-Since to ask the server whether a cached resource has changed. It addresses the bandwidth and latency cost of re-downloading unchanged payloads on every poll or refresh. The trigger is any client that already holds a cached representation and wants to revalidate it cheaply before reusing or replacing it.

send GET with If-None-Match and/or If-Modified-Since → server compares validators → respond 200 with body or 304 with empty body

Field selection is the practice of choosing which structured data fields to include in a prompt sent to an LLM. It addresses context window bloat and noise from irrelevant attributes that dilute model attention. Developers reach for it when designing prompt templates that consume structured records with many optional or nested fields.

identify relevant fields → filter record → format selected fields into prompt template

A batch request combines multiple API operations into a single network call, reducing round-trip overhead. It addresses the latency and throughput costs of issuing many small requests sequentially. Developers reach for it when client code needs to fetch or mutate several related resources and network round-trips become the bottleneck.

collect operations → wrap into single envelope → POST to batch endpoint → parse individual sub-responses

The uniform interface constraint requires that all REST components interact through a standardized, consistent contract regardless of where they are deployed. It addresses the pain point of tightly coupled distributed systems where clients must know implementation details of every server they talk to. Developers reach for it when designing public APIs that must evolve independently of clients and remain decoupled across organizational boundaries.

identify resources → define standard methods → constrain representations → decouple client from server internals

HATEOAS is a REST architectural constraint requiring the server to embed hypermedia links in responses so clients discover available actions dynamically rather than relying on out-of-band URI knowledge. It addresses the pain point of tight client-server coupling where every URI change on the server breaks every consumer. The trigger is designing or evaluating REST APIs that aim for true decoupling and self-descriptive message semantics.

server response embeds hypermedia links → client follows links to transition state → no out-of-band URI knowledge required

Resource identification is the process of defining and naming the addressable entities in a system so each can be uniquely referenced. It addresses the pain point of ambiguity in distributed systems where clients and servers must agree on what is being acted upon. It is triggered when designing APIs, modeling domains, or provisioning infrastructure where stable, unique references to entities are required.

identify noun-based entities → assign unique URIs/IDs → expose via standard operations

Idempotency is a property of an operation whereby applying it once or multiple times produces the same observable result. It addresses the pain point of safely retrying failed requests in unreliable networks without causing duplicate side effects such as double charges or duplicate records. The trigger is designing APIs, message handlers, or database operations that may be retried by clients or by infrastructure.

operation → execute repeatedly → observe same final state as single execution

API versioning is the practice of tagging and exposing distinct versions of an API so that clients can continue using older contracts after the server evolves. It addresses the pain point of breaking existing consumers when an API's schema, endpoints, or behavior change. Developers reach for it whenever a published interface must evolve without forcing coordinated upgrades across all clients.

identify breaking change → choose versioning scheme (URI path, header, query param) → publish new version → deprecate old version with sunset policy

RESTful resource naming defines conventions for structuring URI paths so that endpoints represent resources (nouns) rather than operations (verbs), using HTTP methods to express actions on those resources. It addresses the pain point of inconsistent, action-based, or ambiguous endpoint design that makes APIs hard to discover, document, and consume. The trigger is designing a new HTTP API, reviewing existing endpoints for consistency, or onboarding developers to a service's contract.

plural nouns for collections, singular or {id} for specific items, HTTP verbs (GET/POST/PUT/DELETE) for actions, hierarchical paths for nested resources

URI versioning embeds the API version directly in the resource path (e.g., /api/v1/users), making the version an explicit part of the URL contract. It addresses the pain point of breaking clients when an API evolves by routing old and new clients to different code paths transparently. Developers reach for it when a public API needs backward-incompatible changes without forcing all consumers to migrate at once.

embed version segment in URI path → route to version-specific handler

Subresource nesting is a REST API design pattern where a parent resource embeds or references child resources within its representation, expressed either through URI hierarchy (e.g., /posts/123/comments) or through embedded objects in the response body. It addresses the challenge of representing ownership and containment relationships in a way that clients can navigate without issuing extra discovery requests. Designers reach for it when modeling one-to-many or hierarchical relationships between domain entities that share a clear lifecycle.

parent resource → embedded subresource collection → child resource URI

Pagination and filtering together let clients retrieve subsets of large datasets by combining page-based navigation with predicate-based narrowing. The pain point is that returning entire collections overwhelms network bandwidth, memory, and rendering performance. Developers reach for this pattern whenever an endpoint or query could otherwise return unbounded rows.

fetch page with filters → apply pagination params → return subset with metadata

Resource expansion is the pattern of dynamically allocating additional system resources (memory, compute, connections, storage) to accommodate growing workloads or data volumes. It addresses the pain point of statically sized systems that either waste resources when over-provisioned or fail when under-provisioned. Engineers reach for it when designing systems whose demand profile is unpredictable or monotonically increasing over time.

measure current utilization → detect threshold breach → provision additional resource instances → rebalance workload → release surplus on cooldown

Resource shaping is the deliberate control and constraint of resource consumption (CPU, memory, I/O, network) by a system or application over time. It addresses the pain point of unpredictable performance, resource starvation, or unfair sharing in multi-tenant and contended environments. Engineers reach for it when they need to enforce quotas, guarantee isolation between workloads, or smooth out bursty consumption patterns.

identify resource bottleneck → define constraint policy → apply shaping mechanism → monitor and adjust

Sparse fieldsets let API clients request only the specific fields they need from a resource instead of receiving the full payload. This addresses the pain point of over-fetching data on bandwidth-constrained clients or when resources carry many optional attributes. Developers reach for it when designing or consuming APIs where payload size, latency, or selective retrieval matters and the client already knows which attributes it needs.

GET /resource/?fields=field1,field2 → server returns only requested fields

Compound documents are document database records that embed related sub-documents and arrays within a single parent document rather than normalizing them across separate collections. They address the pain point of expensive cross-collection joins in distributed document stores by co-locating related data. Developers reach for this pattern when modeling one-to-many or hierarchical relationships in document-oriented databases like MongoDB or Couchbase.

embed related sub-documents within a parent document → avoid joins → optimize for read locality

GET /resource issues an HTTP GET request to retrieve the current representation of a named resource from a server. It addresses the need for idempotent, cacheable data retrieval without modifying server state. Use it whenever a client needs to read existing data from a REST endpoint without side effects.

GET /resource

POST /resource is the canonical REST verb-noun pattern for creating a new resource at a named collection endpoint. It addresses the need for a uniform, stateless way to submit data that the server will own and persist. Developers reach for it whenever designing or consuming a REST API where the client needs to create something new rather than retrieve or modify existing state.

POST /{collection} → 201 Created with Location header pointing to /{collection}/{new_id}

PUT /resource/{id} is the REST convention for replacing the full state of a specific resource identified by a path parameter. It addresses the need for a predictable, idempotent way to update an existing entity without ambiguity about which record is being modified. Developers reach for this pattern whenever a client must modify a known resource by its unique identifier rather than create a new one.

PUT /{resource}/{id}

Defines an HTTP DELETE endpoint that removes a specific resource identified by its unique ID from a server-side data store. Addresses the need for a standardized, stateless way to express resource removal in RESTful APIs without relying on custom RPC-style operations. Triggered when designing or consuming CRUD APIs where individual resource deletion must be exposed as a first-class operation.

DELETE /resource/{id}

The PATCH method on a resource endpoint applies a partial update to an existing resource identified by its ID. It addresses the inefficiency of sending entire resource representations when only a few fields change. Developers reach for this when a client needs to modify specific attributes without overwriting the whole record.

PATCH /resource/{id} with partial body → server applies diff → returns updated resource or 200/204

The HTTP HEAD method requests the headers that a GET request to the same resource would return, but transfers no response body. It addresses the need to inspect resource metadata (size, existence, modification time, content type) without paying the bandwidth cost of the full payload. Triggered when validating caches, probing link health, or checking resource state before committing to a download.

HEAD /resource HTTP/1.1

The OPTIONS HTTP method requests information about the communication options available for a target resource, returning allowed methods, headers, and CORS-relevant metadata. It addresses the need for clients to discover server capabilities before making actual requests, particularly across origins. It is triggered when a browser issues a preflight check before a non-simple cross-origin request, or when a client wants to enumerate allowed methods on a resource.

OPTIONS /resource

Defines a REST endpoint that retrieves a specific subresource scoped under a parent resource identified by its ID. Addresses the need to model hierarchical parent-child relationships in RESTful APIs where child entities only make sense in the context of a parent. Triggered when designing or consuming APIs that expose nested resources such as comments under posts, files under projects, or orders under customers.

GET /resource/{id}/subresource

Defines a REST endpoint that creates a child resource scoped under a specific parent resource identified by path parameter. Addresses the need to model ownership and containment hierarchies in HTTP APIs without flattening the data model. Triggered when designing CRUD operations where a new entity logically belongs to an existing parent and must reference it by ID.

POST /resource/{id}/subresource

This chunk defines a REST API endpoint pattern for replacing the state of a specific subresource that belongs to a parent resource. It addresses the need to modify nested data without flattening the resource hierarchy or losing ownership context. Triggered when designing or consuming APIs where child entities are logically owned by a parent and updates must target a single nested item.

PUT /{parent_resource}/{parent_id}/{subresource}

Defines a REST API endpoint that removes a child resource belonging to a specific parent resource identified by its ID. Addresses the need to manage nested data lifecycles without orphaning references or deleting the parent. Triggered when designing CRUD endpoints for one-to-many relationships where the child has no independent identity outside the parent.

DELETE /resource/{id}/subresource

Defines an HTTP PATCH endpoint that targets a specific sub-resource nested under a parent resource identified by {id}. It addresses the need to modify individual fields of a child resource without replacing the entire sub-resource or disturbing sibling entries. Developers reach for this pattern when a client needs to change one or a few attributes of a nested entity while leaving the rest of the resource tree untouched.

PATCH /{parent_resource}/{parent_id}/{subresource}/{subresource_id}

application/json is the IANA-registered MIME type that identifies a payload as JSON-encoded data. Without it, HTTP receivers have no reliable signal for how to interpret the body, leading to silent misparsing or rejected requests. It is reached for whenever JSON crosses a protocol boundary — request, response, file upload, or stored blob — and the consumer needs to know the encoding contract.

Content-Type: application/json

text/xml is the MIME media type that identifies a payload as XML-formatted text, enabling parsers, browsers, and APIs to correctly interpret the body of a message. It solves the ambiguity of how to deserialize incoming data when multiple formats are possible. It is triggered whenever an HTTP request or response carries XML data and the sender needs to declare the encoding.

Content-Type: text/xml; charset=utf-8

The standard IANA-registered MIME media type that tells HTTP intermediaries and clients that a request or response body is encoded as a Protocol Buffers binary payload. It eliminates ambiguity when servers must choose between JSON, XML, and protobuf encodings on the same endpoint. It is reached for whenever an API exposes protobuf as a first-class content type alongside or instead of JSON.

Content-Type: application/protobuf (request and response headers)

The MIME media type identifier for MessagePack-encoded payloads, used in HTTP Content-Type and Accept headers to signal that a request or response body is serialized using the MessagePack binary format. It addresses the ambiguity of transmitting compact binary data over text-oriented HTTP by giving clients and servers a standardized way to negotiate and declare the encoding. Triggered when building or consuming APIs that use MessagePack instead of JSON for smaller, faster payloads.

set Content-Type: application/msgpack on response → client decodes MessagePack body

text/csv identifies a payload as Comma-Separated Values tabular data conforming to RFC 4180. It removes the ambiguity of plain text by declaring the row/column structure so parsers, browsers, and intermediaries can interpret the body correctly. It is reached for whenever a server, client, or tool must signal that a file or HTTP body contains CSV rather than arbitrary text.

Content-Type: text/csv[; charset=<encoding>]

A media type identifier for HAL-formatted JSON responses in REST APIs. It signals to clients that the response body follows the HAL specification, embedding hypermedia `_links` for navigation between related resources. Developers reach for it when designing or consuming hypermedia-driven APIs that need discoverable link relations.

Content-Type: application/hal+json header on responses containing HAL-formatted JSON bodies

The media type identifier for RFC 7807 Problem Details, used in HTTP headers to signal that a response body is a structured JSON document describing an API error. It addresses the pain point of inconsistent, unstructured error responses across REST APIs by giving clients a predictable schema to parse. It is reached for whenever an HTTP API needs to return machine-readable error information instead of plain text or ad-hoc JSON shapes.

HTTP header: Content-Type: application/problem+json (server response) | Accept: application/problem+json (client request)

The IANA-registered MIME media type for JSON-LD (JSON for Linking Data), a JSON-based serialization for representing structured, machine-readable linked data on the web. It signals to parsers, crawlers, and APIs that the payload should be interpreted as a semantic graph rather than plain JSON. Developers reach for it whenever they need to embed or serve schema.org / RDF-backed metadata alongside regular JSON traffic.

declare Content-Type: application/ld+json OR <script type="application/ld+json"></script>

The IANA-registered MIME type for the JSON:API specification, used in HTTP Content-Type and Accept headers to signal that request and response bodies follow the JSON:API document format. It eliminates ambiguity about which JSON dialect is being exchanged, preventing clients from misparsing server payloads or servers from rejecting well-formed JSON:API requests. Reached for whenever a service implements or consumes the JSON:API standard and needs to negotiate the wire format over HTTP.

Content-Type: application/vnd.api+json (response) | Accept: application/vnd.api+json (request)

The application/cbor media type identifies HTTP message bodies encoded as CBOR (Concise Binary Object Representation), a binary data format defined in RFC 8949. It solves the problem of clients and servers needing to agree on a compact, schema-less binary encoding when JSON's verbosity or text-based nature is undesirable. This media type is reached for when designing APIs that prioritize payload size, parsing speed, or strict typing over human readability.

Content-Type: application/cbor in HTTP responses; Accept: application/cbor in HTTP requests for content negotiation

The MIME media type identifier for HTTP PATCH request bodies that follow the JSON Patch specification (RFC 6902). It solves the problem of distinguishing partial-update operation lists from full-resource representations during HTTP content negotiation. Reached for when implementing or consuming a REST endpoint that accepts structured, ordered modifications to a resource.

set Content-Type header to application/json-patch+json and send JSON Patch operation array in request body

Header versioning is an API versioning strategy where the API version is communicated through HTTP request or response headers rather than in the URL path or query string. It addresses the need to keep URLs clean and stable while still allowing clients to negotiate which version of the API they receive. This approach is triggered when designing REST APIs where URL aesthetics, caching behavior, or content negotiation semantics matter.

client sends Accept or X-API-Version header → server routes to versioned handler → response served with version metadata

Query parameter versioning appends a version indicator to the URL query string (e.g., ?version=2) to route clients to the correct API implementation. It addresses the pain of evolving an API without breaking existing consumers by letting clients opt into new behavior explicitly. This approach is reached for when teams want versioning without restructuring URL paths or adding new headers.

GET /resource?version=N → route to vN handler → return versioned response