Definition
POST is the HTTP method for creating new resources or submitting data that causes side effects on the server. When you submit a form, upload a file, or create a new record via an API, you’re typically using POST.
POST is not idempotent - sending the same POST request twice might create two resources. It’s also not safe - POST is explicitly meant to modify server state. The request data goes in the body (not the URL), allowing large payloads like images, documents, or complex JSON structures.
POST is the most flexible HTTP method. While it’s primarily for creation, POST can handle any operation that doesn’t fit other methods’ semantics - complex searches, batch operations, or workflows that don’t map to simple CRUD.
Example
User Registration: Creating a new account sends POST /users with username, email, and password in the request body.
Blog Post Creation: Publishing a new article is POST /posts with the title, content, and metadata.
File Upload: Uploading a profile picture uses POST /users/123/avatar with the image file in the body.
Form Submission: Contact form submission sends POST /contact with name, email, and message.
Payment Processing: Charging a credit card is POST /payments with amount, card details, and customer ID.
Code Example
// POST to create resource
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 67
{
"name": "Alice",
"email": "[email protected]",
"password": "hashed_password"
}
// Response
HTTP/1.1 201 Created
Location: /api/users/123
Content-Type: application/json
{
"id": 123,
"name": "Alice",
"email": "[email protected]",
"created": "2026-01-09T10:30:00Z"
}
Security Notes
CRITICAL: POST creates new resources. Use idempotency keys for safe retries.
Semantics:
- Creates new resource: POST typically creates subordinate resource
- Non-idempotent: Multiple POSTs create multiple resources
- Response body: Typically returns created resource
- Status code: 201 Created (with Location header)
- Location header: URL of newly created resource
Request Processing:
- Validate input: Validate all required fields present
- Business logic: Apply business rules before creation
- Database insert: Insert new record atomically
- Response generation: Return created resource
Idempotency:
- Not idempotent by default: Multiple POSTs create multiple resources
- Idempotency-Key header: Client provides key for safe retries
- Duplicate detection: Server detects duplicate requests
- Same response: Return same response for duplicate request
Security:
- Authorization: Verify user can create resource
- Rate limiting: Limit POST requests to prevent abuse
- Input validation: Sanitize input to prevent injection
- CSRF protection: Include CSRF tokens
- Size limits: Limit request body size
HTTP Semantics:
- Body required: POST typically requires request body
- Content-Type: Specify payload format
- Encoding: Support various encodings (JSON, form-urlencoded)
- Caching: Responses should not be cached
Best Practices
- Return 201 Created for successful resource creation
- Include Location header with URL of newly created resource
- Validate all input data thoroughly
- Implement CSRF protection for web forms
- Use idempotency keys for critical operations (payments)
- Rate limit to prevent abuse
- Return the created resource in response body
- Use proper Content-Type (application/json, multipart/form-data)
- Implement proper error handling with descriptive messages
- Consider using 202 Accepted for async processing
Common Mistakes
Returning 200 OK instead of 201 Created, missing Location header, not validating input, using GET for state-changing operations, no CSRF protection, allowing duplicate submissions, poor error messages, not sanitizing inputs, missing rate limiting, inadequate logging.