← Systems Analysis: APIs, Integrations and Data
Lesson
HTTP methods: safety, idempotency, PUT vs PATCH
Choose the HTTP method for an operation by its properties — safe, idempotent — and explain the difference between POST, PUT and PATCH using an order.
What each method promises
What each method promises
A safe method does not change the server state: GET, HEAD, OPTIONS. Browsers, proxies and crawlers may repeat such requests or send them ahead of time. So GET /orders/9001/cancel is a design error: an accidental repeat cancels the order.
An idempotent method: repeating the same request leaves the server in the same state as one request. These are GET, PUT, DELETE and all safe methods. The response may differ: a second DELETE may return 404, but the resource is already gone — same state.
• POST is not idempotent: two POST /orders, two orders.
• PATCH does not guarantee it: “set the address” can be repeated, “add 1 to the quantity” cannot.
Why an analyst cares: networks fail, clients retry. An idempotent request is safe to retry; POST needs an idempotency key (unit 4).
PUT replaces the whole resource: what is missing from the body disappears, or the server rejects the incomplete body. PATCH changes only the fields sent: PATCH /orders/9001 with {"comment": "Ring the doorbell"} changes just the comment. In JSON Merge Patch (RFC 7396), null means “remove the field”: {"comment": null} erases the comment.
Cancelling is not deleting: a cancelled order stays in the history for money and reports. Two styles exist — POST /orders/9001/cancel or PATCH with the status cancelled. Pick one for the whole API and record it in the contract. DELETE /orders/9001 for cancelling is a trap.
Method properties
| Method | Safe | Idempotent | At Romashka |
|---|---|---|---|
| GET | yes | yes | get an order or a list of orders |
| POST | no | no | create an order, cancel an order |
| PUT | no | yes | save the “home” address in full: PUT /v1/customers/42/addresses/home |
| PATCH | no | not guaranteed | change the comment on an order |
| DELETE | no | yes | delete the saved “home” address |
Lesson notes
What each method promises
A safe method does not change the server state: GET, HEAD, OPTIONS. Browsers, proxies and crawlers may repeat such requests or send them ahead of time. So GET /orders/9001/cancel is a design error: an accidental repeat cancels the order.
An idempotent method: repeating the same request leaves the server in the same state as one request. These are GET, PUT, DELETE and all safe methods. The response may differ: a second DELETE may return 404, but the resource is already gone — same state.
• POST is not idempotent: two POST /orders, two orders.
• PATCH does not guarantee it: “set the address” can be repeated, “add 1 to the quantity” cannot.
Why an analyst cares: networks fail, clients retry. An idempotent request is safe to retry; POST needs an idempotency key (unit 4).
PUT replaces the whole resource: what is missing from the body disappears, or the server rejects the incomplete body. PATCH changes only the fields sent: PATCH /orders/9001 with {"comment": "Ring the doorbell"} changes just the comment. In JSON Merge Patch (RFC 7396), null means “remove the field”: {"comment": null} erases the comment.
Cancelling is not deleting: a cancelled order stays in the history for money and reports. Two styles exist — POST /orders/9001/cancel or PATCH with the status cancelled. Pick one for the whole API and record it in the contract. DELETE /orders/9001 for cancelling is a trap.