Meaning
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.
Primary Function
API design
Communicative Purpose
Enables creation of child resources whose lifecycle and authorization are bound to a specific parent resource identified in the URL path.
Pattern
POST /resource/{id}/subresource
Core Structure
POST /.../{...}/...
Função primária
API design
Propósito comunicativo
Enables creation of child resources whose lifecycle and authorization are bound to a specific parent resource identified in the URL path.
Situações de gatilho
REST API design: creating a comment under a blog post; E-commerce: adding an item to a user's cart; File management: uploading a file into a project folder; SaaS apps: creating a seat under a workspace
Contextos
RESTful web services, Flask/Django/FastAPI/Express backends, OpenAPI specifications, microservice interfaces
Padrão
POST /resource/{id}/subresource
Estrutura central
POST /.../{...}/...
Slots de substituição
resource: string (parent collection name, plural noun); id: int or string (parent resource identifier from path); subresource: string (child collection name, plural noun)
Colocados típicos
- 201 Created response status
- JSON request body
- authentication middleware
- path parameter validation
- parent existence check
- database persistence layer
- OpenAPI path documentation
Substituições comuns
- PUT /resource/{id}/subresource/{sub_id} for full replacement of existing child
- PATCH /resource/{id}/subresource/{sub_id} for partial updates
- flat POST /subresources?parent_id={id} when nesting adds no semantic value
Erros comuns
Using GET instead of POST for creation — GET is idempotent and retries can produce duplicates; omitting parent existence validation — allows orphan subresources with dangling foreign keys; returning 200 OK instead of 201 Created — violates HTTP semantics and breaks client retry logic; nesting four or more levels deep — URL paths become unmaintainable and cache-unfriendly; forgetting authorization at the parent level — any authenticated user can create subresources under any parent ID
Similar / contraste
POST /resource/{id} — creates a top-level resource with no parent; POST /resource/{id}/subresource/{sub_id}/items — three-level nesting for grandchild resources; PUT /resource/{id}/subresource/{sub_id} — replaces an existing child rather than creating a new one
Interferências
Coming from RPC/SOAP: may treat endpoints as remote procedure calls with verbs in the URL — REST uses nouns for resources and HTTP methods for actions; Coming from GraphQL: may try to bundle parent and child mutations into one call — REST requires distinct URLs per resource hierarchy; Coming from Django generic views: may assume automatic URL routing handles all CRUD — nested resources need explicit route registration
Família do chunk
- REST endpoint patterns
- HTTP method semantics
- nested resource routing
- OpenAPI path templating
Nuance
When NOT to use: skip when the subresource has no real ownership of the parent, when the parent ID is already implicit in the auth/session context, or when the relationship is many-to-many without a natural container; Performance: each nesting level typically adds a database join on creation and lookup, so deeply nested routes can degrade write latency; Boundary conditions: must verify the parent resource exists and the caller has write permission on it before accepting the subresource payload, and concurrent POSTs to the same parent must not violate uniqueness constraints on the child.
Efeito pragmático
Establishes explicit resource ownership in the URL, enabling consistent authorization scoping, predictable client-side URL construction, and clean OpenAPI documentation that mirrors the domain model.
Dica de memória
Like adding a chapter to a specific book on a shelf — the book's ID locates exactly which shelf and which book, and the chapter belongs nowhere else.
Upgrade path
POST /resource/{id}/subresource/{sub_id}/action for nested subresource actions, or HATEOAS-style responses with hypermedia links to parent and siblings
Log in to save chunks.