The primary HTTP methods are POST, GET, PATCH, and DELETE. These correspond to create, read, update, and delete (CRUD) operations respectively.
Methods by resource type
| HTTP Method | CRUD | Collection (e.g. /users) | Specific item (e.g. /users/{id}) |
|---|
| GET | Read | 200 OK — list of entities. Use pagination, sorting, and filtering to navigate large lists. | 200 OK — single entity. 404 Not Found if ID not found or invalid. |
| POST | Create | 201 Created — response contains the new resource with its assigned ID. | Not applicable. |
| PATCH | Update | Batch API | 200 OK or 204 No Content. 404 Not Found if ID not found or invalid. |
| DELETE | Delete | 204 No Content. 400 Bad Request if no filter is specified. | 204 No Content. 404 Not Found if ID not found or invalid. |
| PUT | Create/Replace | Not implemented. | Not implemented. |
Idempotency and safety
HTTP methods can be classified by their idempotent and safe properties.
- Safe methods do not modify resources. Calling GET or HEAD will never change a resource.
- Idempotent methods produce the same result regardless of how many times they are called.
| HTTP Method | Idempotent | Safe |
|---|
| OPTIONS | yes | yes |
| GET | yes | yes |
| HEAD | yes | yes |
| PUT | yes | no |
| POST | no | no |
| DELETE | yes | no |
| PATCH | no | no |
GET
Used to read a representation of a resource. On success, GET returns JSON with HTTP status 200 OK. On error, it typically returns 404 Not Found or 400 Bad Request.
GET requests are safe — they only read data and never modify it. Calling GET once has the same effect as calling it ten times.
POST
Used to create new resources. On successful creation, returns HTTP status 201 Created.
POST is not a safe operation. Making two identical POST requests will most likely result in two resources containing the same information but with different identifiers.
PATCH
Used to modify resources. The request body needs to contain only the changes to apply, not the complete resource.
PATCH is not idempotent. Collisions from multiple PATCH requests may corrupt a resource if the patch format requires a known base state. Use conditional requests (GET first, verify no changes, then PATCH) when necessary.
DELETE
Used to delete a resource identified by filters or an ID. On successful deletion, returns HTTP status 204 No Content with no response body.
DELETE permanently removes a resource. Calling DELETE again on the same resource will typically return 404 Not Found because the resource no longer exists.