POST /resource

API Design

Meaning

POST /resource is the canonical REST verb-noun pattern for creating a new resource at a named collection endpoint. It addresses the need for a uniform, stateless way to submit data that the server will own and persist. Developers reach for it whenever designing or consuming a REST API where the client needs to create something new rather than retrieve or modify existing state.

Primary Function

API design

Communicative Purpose

Establishes a uniform, non-idempotent contract for resource creation across distributed clients and servers.

Pattern

POST /{collection} → 201 Created with Location header pointing to /{collection}/{new_id}

Função primária

API design

Propósito comunicativo

Establishes a uniform, non-idempotent contract for resource creation across distributed clients and servers.

Situações de gatilho

REST API design: defining the create endpoint for a new entity type

Contextos

REST APIs, HTTP backends, web frameworks (Express, Flask, Spring, ASP.NET), OpenAPI/Swagger specs, microservice interfaces

Padrão

POST /{collection} → 201 Created with Location header pointing to /{collection}/{new_id}

Colocados típicos

request body (JSON)
201 Created status
Location response header
Content-Type: application/json
idempotency keys
validation middleware

Substituições comuns

PUT /resource/{id} when client controls the ID
POST /resource/{id}/subresource for nested creation
GraphQL mutations for flexible schemas

Erros comuns

Using GET instead of POST for creation — GET must be safe and idempotent, so creation side effects violate the HTTP contract

Similar / contraste

PUT /resource/{id} — idempotent upsert with client-chosen ID

Interferências

Coming from RPC/SOAP: may treat POST as a generic transport for any operation — REST reserves POST specifically for non-idempotent creation under a collection URL

Família do chunk

GET /resource
GET /resource/{id}
PUT /resource/{id}
PATCH /resource/{id}
DELETE /resource/{id}
REST verb-noun routing

Nuance

When NOT to use: when the operation is idempotent and the client knows the ID (use PUT), or when the action is a partial update (use PATCH). Performance: POST bodies are not cached by intermediaries, so large payloads add latency. Boundary condition: POST is not safe and not idempotent by default — retries require an Idempotency-Key header to avoid duplicates.

Efeito pragmático

Standardizing on POST /resource lets every client (mobile, web, partner integrations) create records through one predictable contract, reducing integration bugs and enabling generic middleware like rate limiters and validators.

Dica de memória

POST /resource is like dropping a letter in a mailbox — you hand over the contents, the postal service assigns an address, and you get back a tracking number (Location header) for what you just created.

Upgrade path

Idempotent POST with Idempotency-Key header, or migrate to PUT /resource/{id} when the client can supply the identifier

Frequência: Very highFormulaicidade: Semi-fixedPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term