RESTful resource naming

API Design

Meaning

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.

Primary Function

API design

Communicative Purpose

Ensures consistent, predictable URI structures that expose resources rather than operations, enabling self-documenting and tooling-friendly interfaces.

Pattern

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

Função primária

API design

Propósito comunicativo

Ensures consistent, predictable URI structures that expose resources rather than operations, enabling self-documenting and tooling-friendly interfaces.

Situações de gatilho

Web API design: defining endpoint paths for CRUD operations on domain entities

Contextos

REST APIs, HTTP web services, microservices, OpenAPI/Swagger specifications, Spring Boot, Express, Django REST Framework, FastAPI

Padrão

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

Colocados típicos

HTTP methods (GET
POST
PUT
DELETE
PATCH)
URI paths
plural nouns
nested resources
OpenAPI specs
content negotiation
idempotency

Substituições comuns

RPC-style action endpoints (e.g.
/getUser vs /users/{id}): simpler for trivial operations but breaks REST semantics
GraphQL schemas: single endpoint with client-driven queries
trades caching for flexibility

Erros comuns

Using verbs in resource paths (e.g., /getUsers instead of /users): conflates resources with operations and breaks REST semantics

Similar / contraste

RPC-style naming: action-oriented paths vs. resource-oriented paths

Interferências

Coming from RPC/SOAP: may default to verb-based endpoints (e.g., /getUser) — REST uses nouns for resources and delegates actions to HTTP methods

Família do chunk

REST architectural constraints
HTTP methods semantics
URI design
API versioning strategies
HATEOAS
Richardson Maturity Model

Nuance

When NOT to use: for non-resource operations like complex searches, calculations, or batch actions that don't map cleanly to CRUD — use query parameters, dedicated action endpoints, or GraphQL instead

Efeito pragmático

Consistent resource naming makes APIs self-documenting, reduces client onboarding time, enables automated client SDK generation, and simplifies API governance across teams.

Dica de memória

RESTful resource naming is like organizing a library: shelves (collections) hold books (items), and you find them by location, not by asking the librarian to perform a verb-based action.

Upgrade path

HATEOAS (Hypermedia as the Engine of Application State) and Richardson Maturity Model Level 3 for fully discoverable APIs

Frequência: HighFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term