Safe and Idempotent
- Safe means the action carries no side effects. GET is safe.
- Idempotent means that the outcome is the same no matter how many times you call the action. GET, PUT, & DELETE are all idempotent.
- 201 Created - when the action created a request. Should respond with a Location header with the address of the new resource.
- 204 No Content - when the action completed successfully and the client should expect no response body.
- 400 Bad Request - when the request did not meet requirements, or provide all necessary information required to complete the action.
- 405 Method Not Allowed - when the URI template does not support the method, irrespective of the status of the resource it represents. An Allow response header should be returned that specifies a comma separated list of methods that are permitted.
- 409 Conflict - when the method performed on a URI is at odds with the current status of the resource. E.g, trying to PUT on a URI representing a resource that is deleted.
- 412 Precondition Failed - when the attempted action fails an If-Match or similar header. See Conditional Request Headers below.
POST vs PUT vs PATCH
- When you POST, you are asking the server to create you a resource. The response should contain a Location header with the URI of the object created.
- PUTting on a URI instructs the server to update the entire resource with the representation supplied in the request body. i.e. to overwrite the resource entirely.
- PATCHing is asking to overwrite a specific part of the resource, so the request body is smaller and the rest of the existing resource remains as is.
Conditional Request Headers
Should the ETag not match, then the server should return a 412 Precondition Failed response code. This implies that the client should perform a GET request to obtain the latest ETag of the resource, so that the client is aware of the latest version of the resource before making changes. This tries to enforce changes being overwritten by sending change requests from an out-of-date client.
Also supported is an If-None-Match request header which should also act on the ETag value. If-Match and If-None-Match should also support Wildcard (*) character matching. Additionally, If-Modified-Since and If-Unmodified-Since since request headers are available, to be compared to the value of the Last-Modified response header. These operate on date-time values and are specific to the second.