POST Method — Creating Resources

POST for Resource Creation

The POST method submits data to a specified resource and typically causes a change in state on the server. In REST APIs, POST is the standard method for creating new resources when the server assigns the resource identifier.

Properties

Property	Value
Safe	No
Idempotent	No
Cacheable	Only with explicit headers
Request Body	Yes (required)

Creating a Resource

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Charlie",
  "email": "charlie@example.com",
  "role": "editor"
}

Successful Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/42

{
  "id": 42,
  "name": "Charlie",
  "email": "charlie@example.com",
  "role": "editor",
  "createdAt": "2026-01-15T10:30:00Z"
}

The 201 Created status and the Location header pointing to the new resource are the standard success response for resource creation.

Why POST is Not Idempotent

Calling the same POST request twice creates two separate resources with different IDs. This is a critical difference from PUT, which replaces a resource at a specific URI. Network retries on POST requests must be handled carefully to avoid duplicates.

Beyond Resource Creation

POST is also used for:

• Form submissions — HTML forms default to POST
• File uploads — Using multipart/form-data
• RPC-style calls — Triggering actions like /api/send-email
• Bulk operations — When GET query strings would be too long