Meaning
PUT /resource/{id} is the REST convention for replacing the full state of a specific resource identified by a path parameter. It addresses the need for a predictable, idempotent way to update an existing entity without ambiguity about which record is being modified. Developers reach for this pattern whenever a client must modify a known resource by its unique identifier rather than create a new one.
Primary Function
REST API endpoint design
Communicative Purpose
Enables idempotent full-state replacement of a specific resource addressed by its unique identifier in the URL path.
Pattern
PUT /{resource}/{id}
Core Structure
PUT /.../{...}
Função primária
REST API endpoint design
Propósito comunicativo
Enables idempotent full-state replacement of a specific resource addressed by its unique identifier in the URL path.
Situações de gatilho
REST API: updating an existing resource identified by its primary key Web services: replacing the complete state of an entity via its canonical URI CRUD operations: implementing the 'update' verb in a resource-oriented architecture
Contextos
REST APIs, HTTP web services, CRUD backends, OpenAPI specifications, microservice interfaces
Padrão
PUT /{resource}/{id}
Estrutura central
PUT /.../{...}
Slots de substituição
resource: string (plural resource collection name), id: string or int (unique resource identifier)
Colocados típicos
- GET /resource/{id}
- DELETE /resource/{id}
- PATCH /resource/{id}
- 200 OK
- 204 No Content
- 404 Not Found
- JSON request body
- Content-Type: application/json
- Authorization header
Substituições comuns
- PATCH /resource/{id}: for partial updates instead of full replacement POST /resource/{id}/actions: for non-idempotent operations tied to a resource PUT /resource/{id}/subresource: for nested resource replacement
Erros comuns
Using PUT for partial field updates: PUT semantics require full replacement, so missing fields get wiped — use PATCH instead Returning 201 Created on PUT: 201 implies creation; PUT updates should return 200 OK or 204 No Content Making PUT non-idempotent: side effects beyond state replacement (e.g. logging timestamps, sending emails) break the idempotency contract Omitting the {id} path parameter: PUT without a specific identifier is ambiguous and usually indicates a design error Ignoring If-Match/ETag headers: concurrent updates can silently overwrite each other without optimistic concurrency control
Similar / contraste
PATCH /resource/{id}: partial update vs full state replacement POST /resource: creates a new resource vs updates an existing one DELETE /resource/{id}: removes the resource vs replaces its contents GET /resource/{id}: reads the resource vs modifies it
Interferências
Coming from RPC/SOAP: may treat PUT as a remote procedure call with arbitrary side effects — REST PUT must be idempotent and replace the resource state at the given URI Coming from GraphQL: may expect a single mutation endpoint — REST spreads updates across method+path combinations instead of one query endpoint
Família do chunk
- GET /resource/{id}
- POST /resource
- DELETE /resource/{id}
- PATCH /resource/{id}
Nuance
Do not use PUT when only a subset of fields should change — PATCH is the correct verb for partial updates. PUT requests can be large because they carry the full resource body, so bandwidth and parsing cost scale with resource size. Boundary condition: if the resource at {id} does not exist, some APIs return 404 while others upsert and return 201 — pick one policy and document it.
Efeito pragmático
Standardizes update semantics across clients and servers, enabling safe retries, predictable caching headers, and consistent error handling in distributed systems.
Dica de memória
PUT /resource/{id} is like mailing a complete replacement package to a specific PO box — the box number identifies exactly which item gets swapped out, and sending the same package twice changes nothing.
Upgrade path
PATCH /resource/{id} for partial updates, or ETag/If-Match conditional PUT for optimistic concurrency control
Log in to save chunks.