// HTTP method
POST
Submit data for processing according to the target resource's semantics, often to create a subordinate resource or start an action.
UnsafeNot inherently idempotent. Repeating a POST can create another resource or repeat an action unless the API implements idempotency controls.
Idempotency
Not inherently idempotent. Repeating a POST can create another resource or repeat an action unless the API implements idempotency controls.
Common use cases
- Create a resource with a server-assigned identifier.
- Start a command or processing job.
- Submit a complex search when the request cannot be represented safely in a URL.
Common mistakes
- Assuming automatic retries cannot duplicate work.
- Using POST for every operation without modelling resources.
- Returning 200 when 201 or 202 communicates the result better.
Request
POST /payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: 7bb8...
{ "amount": 4900, "currency": "EUR" }Response
HTTP/1.1 201 Created
Location: /payments/pay_123
{ "id": "pay_123" }// GET STARTED
Design and test a POST operation.
Define the contract in API Designer, then execute it with Cloud Runner or Browser Runner.