API design

Enables targeted, idempotent updates to nested resources while preserving the parent-child relationship in the URL hierarchy.

REST API design: updating a single item within a collection owned by a parent resource; Microservices: modifying a related entity without exposing the parent's full collection; CRUD operations: replacing the state of a specific nested record

RESTful APIs, web services, microservices, HTTP-based backends, OpenAPI specifications

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

PUT /{...}/{...}/{...}

parent_resource: string (plural noun for the owning collection), parent_id: identifier type (int, UUID, string), subresource: string (plural noun for the child collection or singular item identifier)

• HTTP status codes (200
• 204
• 404)
• JSON request body
• Content-Type application/json header
• authentication middleware
• path parameter validation

• PATCH /resource/{id}/subresource — partial update instead of full replacement
• PUT /subresource/{id} — flattened hierarchy loses parent context
• POST /resource/{id}/subresource/{sub_id} — non-idempotent action verb for creation

Using POST instead of PUT — POST is non-idempotent and signals creation, causing duplicate side effects on retry; Omitting the parent ID — flattens the hierarchy and creates ambiguity when subresource IDs collide across parents; Returning 200 with the full updated resource vs 204 No Content — inconsistent with client expectations and caching behavior; Not validating that the subresource belongs to the parent — allows cross-parent data leakage; Using singular nouns in the path — breaks REST collection conventions

PUT /resource/{id} — updates the parent itself, not a child; DELETE /resource/{id}/subresource/{sub_id} — removes rather than replaces; PATCH /resource/{id}/subresource — partial update of the subresource

Coming from RPC/SOAP: may treat the endpoint as an action-oriented method rather than a resource-oriented noun phrase — REST treats the URL as the address of the thing being modified, not the operation name. Coming from GraphQL: may try to express nested updates through a single mutation with complex input types — REST uses distinct URL paths per resource level.

• REST resource nesting
• HTTP verb semantics
• idempotent updates
• subresource CRUD
• URL hierarchy design

When NOT to use: avoid deep nesting beyond two levels (e.g., /a/{id}/b/{id}/c/{id}) as it becomes unreadable and suggests the data model needs flattening. Performance: each PUT replaces the entire subresource representation, so large payloads increase bandwidth — use PATCH for partial updates. Boundary conditions: PUT must be idempotent — repeated identical requests must yield the same server state; if the subresource does not exist, some APIs return 404 while others upsert with 201.

Provides a predictable, cacheable, and idempotent URL contract for updating nested data, enabling reliable client retries and clear API documentation.

PUT to a nested address is like mailing a corrected letter to a specific apartment in a building — the building (parent) and apartment (subresource) together pinpoint exactly what gets updated.

PUT /resource/{id}/subresource/{sub_id}/action — adding sub-resource actions, or transitioning to PATCH for partial updates and GraphQL mutations for complex nested writes