Promptary
Backend ยท REST API

REST API developer concepts

Learn 85 REST API concepts for Backend development, with definitions, aliases, and ready-to-use AI prompts.

Resource design foundations

REST architectural style

Organizes an API around addressable resources, representations, and a uniform HTTP interface.

Also known as
Representational State Transfer, REST style, REST constraints
AI prompt
Apply the REST architectural style pattern to a production REST API. Model business capabilities as resources, keep requests stateless, use standard method semantics, and separate the public contract from storage and framework details. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

API base URL

Provides the stable scheme, host, and root path shared by an API's endpoints.

Also known as
Base endpoint, API origin, Service base URL
AI prompt
Apply the API base URL pattern to a production REST API. Choose one canonical HTTPS origin per environment, keep tenant and resource identifiers out of configuration when possible, and make client construction unambiguous. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Resource

Represents a domain entity or capability that clients can identify and manipulate.

Also known as
REST resource, Domain resource, API entity
AI prompt
Apply the Resource pattern to a production REST API. Model a cohesive business concept rather than a table row, expose only contract fields, and define its lifecycle, ownership, and allowed state transitions. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Resource identifier

Uniquely identifies one resource without exposing mutable presentation details.

Also known as
Resource ID, API identifier, Entity identifier
AI prompt
Apply the Resource identifier pattern to a production REST API. Use an immutable, URL-safe and documented identifier format; validate length and syntax; avoid sequential secrets and direct database coupling. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Resource representation

Serializes the current state and links of a resource for transfer to a client.

Also known as
REST representation, Resource document, API payload
AI prompt
Apply the Resource representation pattern to a production REST API. Define a versioned public schema, omit unauthorized fields, use consistent names and formats, and keep representation details independent from persistence models. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Collection resource

Represents a set of related resources with its own query and creation behavior.

Also known as
Resource collection, List resource, Collection endpoint
AI prompt
Apply the Collection resource pattern to a production REST API. Treat the collection as a first-class resource with filtering, stable ordering, pagination, an empty result shape, and POST creation semantics when supported. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Singleton resource

Represents one resource that exists at a stable non-parameterized path.

Also known as
Single-instance resource, Settings resource, Singleton endpoint
AI prompt
Apply the Singleton resource pattern to a production REST API. Use a stable noun path, define whether absence is possible, authorize against the current principal, and avoid pretending a singleton is a one-item collection. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Subresource

Exposes a meaningful part or capability of a parent resource at its own path.

Also known as
Child resource, Contained resource, Resource component
AI prompt
Apply the Subresource pattern to a production REST API. Use a subresource only when it has independent semantics or permissions, keep nesting shallow, and define what happens when the parent is unavailable. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Nested resource path

Expresses scoped containment through a parent and child resource path.

Also known as
Nested route, Child collection path, Hierarchical endpoint
AI prompt
Apply the Nested resource path pattern to a production REST API. Use nesting to communicate real ownership or scope, avoid paths deeper than necessary, and retain a canonical URL when the child is also addressable globally. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Resource relationship

Connects related resources without requiring clients to understand database joins.

Also known as
Resource association, Related resource, API relationship
AI prompt
Apply the Resource relationship pattern to a production REST API. Expose relationships through stable links, identifiers or shallow related-resource endpoints and define cardinality, authorization, deletion, and missing-target behavior. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Stateless API

Makes every request self-contained so any suitable server instance can process it.

Also known as
Stateless request, REST statelessness, Session-independent API
AI prompt
Apply the Stateless API pattern to a production REST API. Carry required authentication and request context explicitly, store durable workflow state as resources, and avoid hidden conversational state or sticky-session requirements. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Uniform interface

Uses consistent resource, method, status, representation, and link semantics across the API.

Also known as
Consistent REST interface, REST uniformity, Standard interface
AI prompt
Apply the Uniform interface pattern to a production REST API. Establish shared conventions for naming, methods, status codes, errors, pagination, concurrency and links so clients do not relearn each endpoint. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Endpoint operations & workflows

REST endpoint

Combines an HTTP method and resource path into one documented API operation.

Also known as
API route, Resource endpoint, HTTP operation
AI prompt
Apply the REST endpoint pattern to a production REST API. Define one clear purpose, validate all inputs, use correct HTTP semantics, return a documented representation, and keep transport handling separate from domain logic. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

List resources operation

Retrieves a bounded page from a collection resource.

Also known as
List endpoint, Collection GET, Index operation
AI prompt
Apply the List resources operation pattern to a production REST API. Support stable ordering, filtering and pagination from the first release, apply per-item authorization, and return an empty collection rather than an ambiguous null. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Get resource operation

Retrieves the current representation of one identified resource.

Also known as
Read endpoint, Resource GET, Fetch operation
AI prompt
Apply the Get resource operation pattern to a production REST API. Distinguish invalid, missing and forbidden targets safely; avoid side effects; support conditional retrieval where useful; and return a stable response model. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Create resource operation

Creates a new resource within a collection or at a client-selected identifier.

Also known as
Create endpoint, Collection POST, Resource creation
AI prompt
Apply the Create resource operation pattern to a production REST API. Validate before mutation, make the transaction atomic, define server-generated fields, return 201 with Location, and support idempotency when clients may retry. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Replace resource operation

Replaces the complete mutable state of a resource at a known URI.

Also known as
Full update, Resource PUT, Replacement endpoint
AI prompt
Apply the Replace resource operation pattern to a production REST API. Require a complete representation, define create-on-missing behavior, protect concurrent writes, and never silently treat omitted fields as an implicit partial update. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Partial update operation

Changes selected fields without requiring a complete resource replacement.

Also known as
PATCH endpoint, Partial modification, Resource patch
AI prompt
Apply the Partial update operation pattern to a production REST API. Choose and document a patch format, reject immutable or unknown fields, validate the resulting resource, apply atomically, and use concurrency protection. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Delete resource operation

Removes, deactivates, or schedules removal of an identified resource.

Also known as
Delete endpoint, Resource DELETE, Removal operation
AI prompt
Apply the Delete resource operation pattern to a production REST API. Define hard versus soft deletion, dependent-resource behavior, authorization, audit requirements, idempotent repetition, and whether recovery is possible. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Custom action endpoint

Models a domain command that does not fit standard create, read, update, or delete semantics.

Also known as
Action operation, Command endpoint, Custom method
AI prompt
Apply the Custom action endpoint pattern to a production REST API. Use custom actions sparingly, attach the action to its resource or collection, use a verb name, validate state transitions, and make retry behavior explicit. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Batch request

Carries several independent API operations in one network request.

Also known as
API batch, Multi-request envelope, Request bundle
AI prompt
Apply the Batch request pattern to a production REST API. Define maximum operations and payload size, per-operation authorization and status, dependency rules, atomicity boundaries, ordering, and partial-failure behavior. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Bulk operation

Applies one operation to many resources using a single bounded command.

Also known as
Bulk endpoint, Mass operation, Collection command
AI prompt
Apply the Bulk operation pattern to a production REST API. Limit target count, authorize every item, define all-or-nothing versus per-item outcomes, use asynchronous processing when needed, and expose a result resource. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Upsert operation

Creates a resource when absent or updates it when the client-controlled key already exists.

Also known as
Create or update, Put-if-absent, Upsert endpoint
AI prompt
Apply the Upsert operation pattern to a production REST API. Use only when the client controls the canonical identifier, keep the operation idempotent, distinguish created from updated, validate complete state, and protect concurrent writes. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Soft delete

Marks a resource as deleted while retaining it for recovery, audit, or retention.

Also known as
Logical deletion, Tombstone, Archived deletion
AI prompt
Apply the Soft delete pattern to a production REST API. Define visibility after deletion, uniqueness behavior, retention, cascading rules, authorization, audit data, and permanent purge separately. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Restore resource operation

Returns a soft-deleted or archived resource to an active state.

Also known as
Undelete endpoint, Recovery action, Restore action
AI prompt
Apply the Restore resource operation pattern to a production REST API. Require a valid tombstone state, recheck permissions and uniqueness constraints, define expired-retention behavior, and record an audit event. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Asynchronous request-reply

Accepts work immediately and provides a separate way to observe eventual completion.

Also known as
202 pattern, Async API operation, Deferred response
AI prompt
Apply the Asynchronous request-reply pattern to a production REST API. Validate synchronously, return 202 with a status location and retry guidance, make submission retry-safe, and persist observable operation state. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Long-running operation

Represents work that continues beyond a normal request timeout.

Also known as
LRO, Extended operation, Background API operation
AI prompt
Apply the Long-running operation pattern to a production REST API. Expose durable progress, terminal success and failure details, result links, cancellation policy, expiry, retry-safe creation, and bounded polling guidance. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Operation status resource

Provides the current state and result links for asynchronous API work.

Also known as
Job status endpoint, Operation resource, Progress resource
AI prompt
Apply the Operation status resource pattern to a production REST API. Use a stable operation identifier, explicit pending/running/succeeded/failed/cancelled states, progress only when meaningful, Retry-After, result links, and expiry metadata. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Operation cancellation

Requests cancellation of a running asynchronous operation.

Also known as
Cancel job endpoint, Abort operation, LRO cancellation
AI prompt
Apply the Operation cancellation pattern to a production REST API. Define cancellable states, idempotent repeated cancellation, race behavior with completion, cleanup guarantees, permission checks, and the final cancelled result. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Change feed

Returns resources or events changed since a client-held continuation point.

Also known as
Delta query, Incremental sync, Changes endpoint
AI prompt
Apply the Change feed pattern to a production REST API. Use opaque expiring cursors, deterministic ordering, tombstones for deletions, tenant scoping, bounded pages, replay-safe semantics, and a documented full-resync path. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Querying & collection traversal

Collection filtering

Restricts a collection using documented field and operator conditions.

Also known as
API filters, Filtered list, Query filter
AI prompt
Apply the Collection filtering pattern to a production REST API. Allowlist filterable fields and operators, validate types and complexity, parameterize storage queries, preserve filters across pagination, and document authorization effects. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Collection sorting

Orders collection results by one or more documented fields.

Also known as
API ordering, Sort parameter, Order by
AI prompt
Apply the Collection sorting pattern to a production REST API. Allowlist sortable fields, define direction syntax, add a unique tie-breaker, use matching indexes, and retain the same ordering for every page. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Search query

Finds resources using a relevance or domain-specific text query.

Also known as
API search, Query endpoint, Full-text parameter
AI prompt
Apply the Search query pattern to a production REST API. Define searchable fields and matching behavior, normalize safely, limit query cost, disclose ranking and pagination behavior, and keep authorization inside the search boundary. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Sparse fieldsets

Lets clients request a documented subset of response fields.

Also known as
Field selection, Fields parameter, Projection
AI prompt
Apply the Sparse fieldsets pattern to a production REST API. Validate requested public fields, always retain required identity and link data, apply field-level authorization, vary caches correctly, and avoid leaking hidden schema names. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Resource expansion

Optionally embeds selected related resources in one response.

Also known as
Expand parameter, Embedded resource, Relationship expansion
AI prompt
Apply the Resource expansion pattern to a production REST API. Allowlist expansions, cap depth and fan-out, authorize related resources independently, prevent N+1 queries, and keep canonical links alongside embedded data. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Relationship inclusion

Includes specified related resource documents alongside primary collection data.

Also known as
Include parameter, Compound document, Related data inclusion
AI prompt
Apply the Relationship inclusion pattern to a production REST API. Document include paths, cap breadth and depth, deduplicate included resources, preserve linkage, apply authorization, and bound response size. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Offset pagination

Pages through a collection using an item offset and limit.

Also known as
Limit-offset paging, Skip-take pagination, Offset paging
AI prompt
Apply the Offset pagination pattern to a production REST API. Set maximum limits, stable ordering and deterministic ties, document behavior under concurrent changes, optimize large offsets, and prefer cursor pagination for volatile large collections. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Cursor pagination

Uses an opaque continuation value to advance through a stable ordered collection.

Also known as
Cursor-based paging, Token pagination, Opaque pagination
AI prompt
Apply the Cursor pagination pattern to a production REST API. Sign or encrypt opaque cursor state, bind it to filters and ordering, enforce expiry and page limits, support direction deliberately, and never require clients to construct tokens. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Keyset pagination

Uses the last ordered key values to efficiently retrieve the next collection slice.

Also known as
Seek pagination, After-key paging, Index pagination
AI prompt
Apply the Keyset pagination pattern to a production REST API. Use a unique composite order, validate anchor values, match database indexes, preserve filters, define forward and reverse navigation, and avoid gaps from non-deterministic sorting. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Page size limit

Controls the requested and maximum number of resources returned per page.

Also known as
Limit parameter, Page limit, Result size
AI prompt
Apply the Page size limit pattern to a production REST API. Choose a safe default and maximum, validate invalid values, let the server return fewer items, include continuation independently of count, and document cost-sensitive endpoints. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Continuation token

Carries opaque state needed to resume a paginated traversal.

Also known as
Next token, Page token, Resume cursor
AI prompt
Apply the Continuation token pattern to a production REST API. Keep tokens opaque, tamper-resistant, scoped to tenant and query, time-bounded, versioned internally, and safe to replay without exposing storage keys. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Total result count

Reports the number of matching resources when the service can calculate it deliberately.

Also known as
Collection count, Total records, Result total
AI prompt
Apply the Total result count pattern to a production REST API. Make count optional when expensive, distinguish exact from estimated counts, apply the same filters and authorization, and do not confuse page size with total size. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Stable collection ordering

Guarantees deterministic item order across pages by adding a unique tie-breaker.

Also known as
Deterministic sort, Pagination order, Stable sort
AI prompt
Apply the Stable collection ordering pattern to a production REST API. Define a default order, append a unique immutable tie-breaker, use consistent null and collation rules, and bind cursors to the ordering definition. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Empty collection response

Represents a successful collection query with no matching resources.

Also known as
Zero-result response, Empty list, No matches
AI prompt
Apply the Empty collection response pattern to a production REST API. Return the normal collection schema with an empty array, stable pagination metadata and no false 404, while distinguishing an invalid parent scope when relevant. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Contracts, representations & errors

Request model

Defines the public fields accepted by an API operation.

Also known as
Request DTO, Input schema, Command model
AI prompt
Apply the Request model pattern to a production REST API. Use a dedicated schema rather than a persistence model, define required and optional fields, constraints, unknown-field behavior, examples, and authorization-sensitive input. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Response model

Defines the stable public representation returned by an API operation.

Also known as
Response DTO, Output schema, View model
AI prompt
Apply the Response model pattern to a production REST API. Use an explicit output model, preserve compatibility, format values consistently, omit secrets and internal state, and support field-level authorization without unstable shapes. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Resource schema

Specifies field names, types, formats, constraints, and nested structures for a resource.

Also known as
API schema, Resource contract, JSON schema
AI prompt
Apply the Resource schema pattern to a production REST API. Define identity, lifecycle fields, nullability, extensibility, formats and examples; reuse components carefully; and keep schema changes compatible. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Request validation

Rejects malformed or semantically invalid API input before business mutation.

Also known as
Input validation, Payload validation, API validation
AI prompt
Apply the Request validation pattern to a production REST API. Validate syntax, types, ranges, cross-field rules and business preconditions; cap complexity; preserve safe error detail; and run authorization at the correct boundary. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Unknown field policy

Defines how a server handles request properties outside the published schema.

Also known as
Extra property handling, Unexpected fields, Strict input policy
AI prompt
Apply the Unknown field policy pattern to a production REST API. Choose reject, ignore or preserve deliberately; prefer clear rejection for writes that would otherwise drop data; keep response readers tolerant of compatible additions. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Required and optional fields

Distinguishes values clients must send from values they may omit.

Also known as
Field presence, Mandatory property, Optional property
AI prompt
Apply the Required and optional fields pattern to a production REST API. Document presence separately from nullability and defaults, make server-generated fields read-only, and avoid adding newly required fields to an existing request contract. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Nullable field

Allows a field to carry an explicit null value with defined meaning.

Also known as
Null property, Nullable value, Explicit null
AI prompt
Apply the Nullable field pattern to a production REST API. Define whether null means clear, unknown or not applicable, distinguish it from an omitted field in updates, and keep serialization and schema behavior consistent. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Evolvable enum contract

Represents a bounded named value while allowing safe future API evolution.

Also known as
API enumeration, String enum, Extensible enum
AI prompt
Apply the Evolvable enum contract pattern to a production REST API. Use stable string values, document unknown-value behavior, avoid renaming meanings, add values only when clients tolerate them, and provide a fallback in generated SDKs. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Response envelope

Wraps primary data with links, metadata, or errors in a consistent top-level object.

Also known as
API wrapper, Data envelope, Response wrapper
AI prompt
Apply the Response envelope pattern to a production REST API. Use an envelope only when it provides consistent value, keep shapes uniform, avoid double nesting, and ensure status and headers remain authoritative for transport semantics. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Response metadata object

Carries non-resource information such as pagination, counts, timing, or warnings.

Also known as
Meta object, Response context, API metadata
AI prompt
Apply the Response metadata object pattern to a production REST API. Use documented names and types, avoid exposing internal diagnostics, keep metadata optional and evolvable, and do not place resource state in the metadata object. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

HATEOAS

Uses representation links and affordances to guide valid next API interactions.

Also known as
Hypermedia API, REST discoverability, Application-state links
AI prompt
Apply the HATEOAS pattern to a production REST API. Expose only currently valid transitions, use stable link relations and media types, preserve normal HTTP semantics, and avoid requiring undocumented URI construction. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Problem details response

Returns machine-readable error details using the standard application/problem+json shape.

Also known as
RFC 9457 error, Problem document, API problem
AI prompt
Apply the Problem details response pattern to a production REST API. Use stable problem type URIs, correct status, concise titles, safe instance identifiers and documented extension members without exposing stack traces or secrets. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Validation error response

Maps one or more input problems to precise fields or parameters.

Also known as
Field errors, Input problem, Constraint violations
AI prompt
Apply the Validation error response pattern to a production REST API. Use stable machine codes plus human messages, JSON Pointer or parameter locations, rejected-value redaction, deterministic ordering, and one response for all useful violations. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Machine-readable error code

Provides a stable programmatic identifier for an API failure condition.

Also known as
API error code, Problem code, Service error identifier
AI prompt
Apply the Machine-readable error code pattern to a production REST API. Define stable names and meanings, map them consistently to HTTP status and problem types, document recovery, keep human text separate, and version breaking semantic changes. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Consistent API status codes

Applies the same HTTP status meaning to equivalent outcomes throughout an API.

Also known as
Status code policy, HTTP outcome mapping, Response status convention
AI prompt
Apply the Consistent API status codes pattern to a production REST API. Use a restrained documented set, distinguish client from server faults, keep error bodies consistent, avoid 200 for failures, and test every declared response path. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Reliability, concurrency & performance

Idempotent operation

Produces the same intended resource effect when an identical request is repeated.

Also known as
Retry-safe mutation, Repeatable operation, Idempotent endpoint
AI prompt
Apply the Idempotent operation pattern to a production REST API. Use natural method semantics or stored request identity, make the effect atomic, handle concurrent duplicates, and return a stable replay outcome. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Idempotency key

Lets a client identify retries of one non-idempotent request.

Also known as
Request key, Deduplication key, Idempotent POST key
AI prompt
Apply the Idempotency key pattern to a production REST API. Scope keys to caller and operation, validate payload fingerprints, reserve atomically, handle in-progress duplicates, retain outcomes for a bounded period, and reject conflicting reuse. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Request deduplication

Prevents repeated delivery from producing duplicate side effects.

Also known as
Duplicate suppression, Replay protection, Exactly-once effect
AI prompt
Apply the Request deduplication pattern to a production REST API. Choose a stable request identity, enforce a unique atomic record, distinguish duplicates from conflicting payloads, replay safe results, and define retention and recovery after partial failure. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Optimistic concurrency

Rejects a write when the resource changed after the client last read it.

Also known as
Version check, Concurrency token, Compare and swap
AI prompt
Apply the Optimistic concurrency pattern to a production REST API. Use strong version validators, compare atomically with the write, return the latest validator and safe recovery guidance, and never silently overwrite newer state. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Retry-safe operation

Defines how clients can repeat an API call after an uncertain network outcome.

Also known as
Safe retry policy, Resilient API call, Repeatable request
AI prompt
Apply the Retry-safe operation pattern to a production REST API. Classify retryable statuses, use idempotency for mutations, honor Retry-After, apply bounded exponential backoff with jitter, and prevent retry storms or duplicate work. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Rate limiting

Restricts request frequency to protect capacity and fair access.

Also known as
API throttling, Request limit, Traffic shaping
AI prompt
Apply the Rate limiting pattern to a production REST API. Define identity, window or token-bucket policy, burst behavior, distributed enforcement, standard limit metadata, retry guidance, exemptions, and monitoring without using IP as identity alone. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

API quota

Caps usage over a longer accounting period such as a day or billing cycle.

Also known as
Usage allowance, Consumption limit, API allocation
AI prompt
Apply the API quota pattern to a production REST API. Define metered units, tenant and plan scope, reset timing, atomic accounting, grace behavior, administrative overrides, and clear exhausted-quota errors. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Payload size limit

Bounds request and response bodies to protect memory, bandwidth, and processing time.

Also known as
Body limit, Maximum payload, Request size cap
AI prompt
Apply the Payload size limit pattern to a production REST API. Enforce compressed and decompressed limits while streaming, advertise upload constraints, avoid buffering untrusted bodies, clean partial files, and return a clear 413 problem. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Request timeout budget

Allocates a bounded deadline across API handling and dependent calls.

Also known as
API deadline, Latency budget, Request time limit
AI prompt
Apply the Request timeout budget pattern to a production REST API. Set endpoint-appropriate limits, propagate the remaining deadline, reserve response time, cancel dependencies, distinguish client and upstream timeouts, and record the timed-out stage. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

API caching policy

Defines when REST responses may be reused and revalidated.

Also known as
REST cache, Response caching, Cache strategy
AI prompt
Apply the API caching policy pattern to a production REST API. Set explicit cache controls and validators, vary on representation dimensions, separate public from private data, prevent sensitive caching, and define invalidation after writes. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

API request correlation

Carries a safe identifier across one API request and its dependent work.

Also known as
Request ID, Correlation ID, Trace request identifier
AI prompt
Apply the API request correlation pattern to a production REST API. Accept or generate a bounded safe ID, propagate it to logs and dependencies, return it for support, avoid embedding personal data, and do not use it as authorization. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Chatty API anti-pattern

Requires many small sequential requests to complete one common client task.

Also known as
Excessive API calls, N plus one API, Fine-grained endpoint anti-pattern
AI prompt
Identify and correct the Chatty API anti-pattern in a production REST API. Measure real workflows, add deliberate expansion, aggregation or bulk operations, preserve domain boundaries, cap fan-out, and avoid replacing one chatty flow with an unbounded response. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Evolution & lifecycle

API versioning

Lets incompatible API contracts coexist while clients migrate deliberately.

Also known as
REST version, Contract versioning, API release version
AI prompt
Apply the API versioning pattern to a production REST API. Version only for breaking contract changes, choose one consistent selection mechanism, maintain clear support windows, test side by side, and minimize long-lived versions. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Path versioning

Places the selected API version in the service root path.

Also known as
URL versioning, URI version, Versioned base path
AI prompt
Apply the Path versioning pattern to a production REST API. Use a stable major version segment, keep resource paths consistent within a version, generate correct links, and document migration and retirement for older roots. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Query parameter versioning

Selects an API contract using a documented query parameter.

Also known as
api-version parameter, Query version, Version query string
AI prompt
Apply the Query parameter versioning pattern to a production REST API. Require and validate one version value consistently, include it in generated links and cache keys, reject unsupported values clearly, and preserve path stability intentionally. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Header versioning

Selects an API contract through a dedicated request header.

Also known as
API version header, Custom header version, Header-based version
AI prompt
Apply the Header versioning pattern to a production REST API. Use one documented header, define defaults and missing behavior, include it in cache variation, make tooling support clear, and avoid invisible version mismatches in copied URLs. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Media type versioning

Selects a representation version through a vendor media type or parameter.

Also known as
Accept versioning, Vendor media type, Content negotiation version
AI prompt
Apply the Media type versioning pattern to a production REST API. Parse Accept correctly, return 406 when unsupported, set Content-Type and Vary, document tooling tradeoffs, and keep method and resource semantics stable across representations. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Backward-compatible API change

Extends an existing contract without breaking conforming clients.

Also known as
Non-breaking change, Compatible evolution, Safe API extension
AI prompt
Apply the Backward-compatible API change pattern to a production REST API. Prefer optional additions and new endpoints, keep existing meanings and defaults, prepare clients for unknown response fields, run compatibility checks, and document behavior changes. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Breaking API change

Changes a contract in a way that can make an existing client fail or behave differently.

Also known as
Incompatible change, Contract break, Major API change
AI prompt
Apply the Breaking API change pattern to a production REST API. Classify removals, renames, tighter validation, type changes and semantic changes; require review, a new supported version, migration guidance, telemetry, and a retirement plan. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

API deprecation policy

Defines how unsupported or superseded API behavior is announced and retired.

Also known as
API retirement policy, Deprecation lifecycle, End-of-support policy
AI prompt
Apply the API deprecation policy pattern to a production REST API. Require an alternative, owner, announcement channels, minimum migration window, usage monitoring, support commitments, and an exception process before retirement. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

Deprecation response header

Signals that a requested API resource or operation has been deprecated.

Also known as
Deprecation header, RFC 9745, API deprecation signal
AI prompt
Apply the Deprecation response header pattern to a production REST API. Emit the standardized header, add a deprecation link, preserve normal response behavior during migration, avoid ambiguous dates, and monitor which clients receive it. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

API sunset

Communicates when a deprecated API is expected to stop responding.

Also known as
Sunset header, Retirement date, End-of-life API
AI prompt
Apply the API sunset pattern to a production REST API. Set a realistic date after policy and usage review, use the Sunset header and migration link, contact active consumers, rehearse shutdown, and retain a rollback plan. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

API changelog

Records released contract additions, fixes, deprecations, and breaking versions.

Also known as
Release notes, API change history, Contract changelog
AI prompt
Apply the API changelog pattern to a production REST API. Publish dates, affected versions and endpoints, compatibility classification, deprecations, fixes and links to updated documentation without mixing internal implementation noise. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.

API migration guide

Explains how clients move from one API contract or pattern to its successor.

Also known as
Upgrade guide, Version migration, API transition guide
AI prompt
Apply the API migration guide pattern to a production REST API. Provide field and endpoint mappings, before-and-after examples, changed semantics, error differences, test strategy, rollout sequence, rollback, deadlines, and support channels. Define the resource and route semantics, request contract, successful response, documented error cases, authorization boundary, validation, retry or concurrency behavior where relevant, and matching OpenAPI examples.