RESTful CRUD Services

Notes from the book Rest In Practice. There's plenty more in the chapter that is not mentioned here, this is just the stuff I found useful/interesting and worth putting down.

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.

Response Codes

• 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.

Entity Tags

An ETag response header is used to identify the version of the resource. Typically, a hash of the response body of a GET request of a resource is used as it is a shorter, unique representation of the entire state of the resource at that moment in time. A version number or date time stamp could also be used.

Conditional Request Headers

An If-Match header can be provided with a PUT request (for example) as a way of telling the server to only perform the associated action if the client is operating on the latest version of the resource. If the value of the ETag returned with a GET request is used as the If-Match header of a PUT request, we are telling the server to make sure that the current ETag of the resource matches the If-Match value the client provided before carrying out the operation.

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.