HTTP POST

Overview

POST submits data to the server to create a new resource or trigger processing. It changes server state so it is not safe, and sending it twice may create two resources so it is not idempotent.

Details

The `Content-Type` header declares the body format (`application/json`, `application/x-www-form-urlencoded`, `multipart/form-data`, etc.). When a new resource is created, the standard is to return 201 Created with a `Location` header pointing to the new URL.

Because POST is not idempotent, a network retry on payment or order endpoints can cause duplicate creation. Prevent it with an idempotency key the client sends and the server de-duplicates. Return 422 for validation failures and 409 for state conflicts.

Request / Response example

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

{ "name": "Ada" }

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

{ "id": 42, "name": "Ada" }

In code

curl -X POST https://api.example.com/api/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Ada' })
});

@app.post('/api/users')
def create_user():
    data = request.get_json()
    uid = db.insert(data)
    return jsonify(id=uid, **data), 201

Typical status codes

Related methods

Related headers