name: REST Vocabulary description: >- Normative vocabulary for REST (Representational State Transfer) architectural style, HTTP semantics, and RESTful API design covering key concepts, constraints, HTTP methods, status codes, and design patterns. version: 1.0.0 created: '2026-05-02' modified: '2026-05-02' terms: - term: Resource definition: >- Any named information that can be identified by a URI. Resources are the fundamental conceptual targets of RESTful API design. A resource can be a document, image, service, collection of other resources, or any other named information. tags: - Core Concept - REST - term: Representation definition: >- A snapshot of a resource's current state, transferred between client and server in a specific format (JSON, XML, HTML). Representations may include metadata (headers) and data (body). REST systems exchange representations, not resources directly. tags: - Core Concept - REST - term: Stateless definition: >- A REST constraint requiring that each request from client to server must contain all information needed to understand the request. Session state is kept entirely on the client. Servers do not store per-client context between requests. tags: - Constraint - REST - term: Uniform Interface definition: >- A REST constraint that simplifies and decouples the architecture by applying four interface constraints: identification of resources in requests, manipulation through representations, self-descriptive messages, and hypermedia as the engine of application state (HATEOAS). tags: - Constraint - REST - term: HATEOAS definition: >- Hypermedia As The Engine Of Application State — a REST constraint where a client interacts with a network application entirely through hypermedia provided dynamically by application servers. Clients need no prior knowledge of the API structure beyond an entry point. tags: - Constraint - REST - term: Cacheable definition: >- A REST constraint requiring that responses label themselves as cacheable or non-cacheable. Caching improves efficiency and scalability by eliminating some client-server interactions. tags: - Constraint - REST - term: Client-Server definition: >- A REST constraint enforcing separation of concerns between UI and data storage. Separation allows components to evolve independently. tags: - Constraint - REST - term: Layered System definition: >- A REST constraint allowing a client to be unable to tell whether it is connected directly to the end server or an intermediary (load balancer, cache, gateway). Layers can enforce security policies and improve scalability. tags: - Constraint - REST - term: Code on Demand definition: >- An optional REST constraint allowing servers to transfer executable code (e.g., JavaScript) to clients. This is the only optional constraint. tags: - Constraint - REST - term: Idempotent definition: >- A property of HTTP methods where making multiple identical requests has the same effect as making a single request. GET, HEAD, PUT, DELETE, OPTIONS, and TRACE are idempotent. POST is not. tags: - HTTP - Safety - term: Safe Method definition: >- HTTP methods that do not modify state on the server: GET, HEAD, OPTIONS, TRACE. Safe methods may still have side effects such as logging. tags: - HTTP - Safety - term: Content Negotiation definition: >- The mechanism for selecting the best representation for a given response when there are multiple representations available. Uses Accept and Content-Type headers to agree on format between client and server. tags: - HTTP - REST - term: HTTP Method definition: >- Indicates the desired action to be performed on a resource. Common REST methods: GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove), HEAD (metadata), OPTIONS (capabilities). tags: - HTTP - Core Concept - term: URI definition: >- Uniform Resource Identifier — a string that identifies a resource. In REST, URIs are the primary mechanism for identifying resources. URLs (Uniform Resource Locators) are URIs that include access protocol and location. tags: - Core Concept - REST - term: Path Parameter definition: >- A variable part of a URL path that identifies a specific resource, denoted by curly braces in templates (e.g., /users/{id}). Path parameters are part of the resource identifier. tags: - API Design - HTTP - term: Query Parameter definition: >- Key-value pairs appended to a URL after a question mark, used for filtering, sorting, pagination, and other non-resource-identifying purposes (e.g., /users?page=2&sort=name). tags: - API Design - HTTP - term: Status Code definition: >- A three-digit HTTP response code indicating the outcome of a request. Key REST conventions: 2xx (success), 3xx (redirection), 4xx (client error), 5xx (server error). Most common: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Internal Server Error. tags: - HTTP - Core Concept - term: Hypermedia definition: >- Non-linear media that includes links to other media, enabling navigation through a REST API. REST APIs using hypermedia expose state transitions as links in responses, allowing clients to discover available actions. tags: - Core Concept - REST - term: API Versioning definition: >- The practice of managing changes to an API to preserve backward compatibility. Common REST versioning strategies include URI path versioning (/v1/users), query parameter versioning (?version=1), and header versioning (Accept: version=1). tags: - API Design - Best Practice - term: OpenAPI Specification definition: >- A standard, language-agnostic interface description for RESTful APIs that allows both humans and computers to discover and understand the capabilities of a service without access to source code. Formerly known as Swagger. tags: - Standards - Tooling