The distinction between POST and PUT is fundamental to HTTP protocol design and RESTful architecture.

Idempotency: The primary rule

  • HTTP PUT is idempotent: Calling PUT /v1/users/123 ten times with the same body results in the exact same state as calling it once.
  • HTTP POST is non-idempotent: Calling POST /v1/users ten times creates ten distinct user accounts with ten distinct identifiers.

URI Assignment: Who chooses the URL?

  1. POST (Server assigns URI): The client sends data to a parent collection URL (POST /v1/orders). The server generates the new ID (order_981) and responds with 201 Created and Location: /v1/orders/order_981.
  2. PUT (Client knows URI): The client specifies the exact URI of the entity (PUT /v1/users/usr_481). The server completely replaces the entity at that URI with the supplied representation.

How to test with curl

curl -i -X PUT https://api.example.test/v1/users/usr_481 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alex", "email": "alex@example.test"}'

Key takeaway

Use POST when submitting data to create a new subordinate resource whose URI is assigned by the server. Use PUT when creating or completely replacing a resource at a client-known URI.