REST And HTTP Status Codes
I’ve seen a fair bit of confusion regarding understanding and using correct HTTP status codes when using REST. This post will go over some of the most common scenarios and the valid HTTP status code that must be returned as part of the request or the response headers.
4xx HTTP Status Codes
When using REST, clients and servers exchange representations of resources. For example, in a POST request, the request body represents the resource to create. In a GET request, the response body represents the fetched resource.
The HTTP protocol specifies formats using media types, also called MIME types.
Content-Type header in a request or response specifies the format of the representation. Consider the following example that specifies the format as JSON.
Content-Type: application/json; charset=utf-8
If the server does not support the media type, it should return the HTTP status code 415(Unsupported Media Type).
A client request can include an Accept header that contains a list of media types the client will accept from the server in the response message. If the server cannot match any media types listed in the Accept header, it should return the HTTP status code 406(Not Accepted).
If the server cannot find the requested resource, the method should return 404 (Not Found). Likewise, if the client puts invalid data into the request, the server should return HTTP status code 400 (Bad Request).
In some cases, it might not be possible to update an existing resource when using PATCH/PUT operations. In that case, consider returning HTTP status code 409 (Conflict).
2XX HTTP Status Codes
If a POST method creates a new resource, it returns an HTTP status code 201 (Created). If the operation does some processing but does not create a new resource, it can return HTTP status code 200 and include the result of the operation in the response body. Alternatively, if nothing is to return, the method can return HTTP status code 204 (No Content) with no response body.
Asynchronous Operations
Sometimes POST, PUT, PATCH, or DELETE operation might require processing that takes a while to complete. If you wait for completion before sending a response to the client, it may cause unacceptable latency. If so, consider making the operation asynchronous. Return HTTP status code 202 (Accepted) to indicate the request was accepted for processing but has not been completed.
It is common to expose an endpoint that returns the status of an asynchronous request, so the client can monitor the status by polling the status endpoint. The Location header contains the URI of the status endpoint.
If the asynchronous operation creates a new resource, the status endpoint should return status code 303 (See Other) after the operation completes. In the 303 response, include a Location header that gives the URI of the new resource.
Partial Responses
A resource may contain large binary fields, such as files or images. Large resources should be retrieved in chunks to improve response times and overcome the issues caused by unreliable connections. Therefore, the API should support the Accept-Ranges header. This header indicates that the GET operation supports partial requests. The client application can submit GET requests that return a subset of a resource, specified as a range of bytes.
It is common to support HEAD requests for such resources. A HEAD request only returns the HTTP headers that describe the resource, with an empty message body. A client can issue a HEAD request to determine whether the API supports partial GET requests.
The response message of a partial response should return HTTP status code 206(Partial Content). The Content-Length header specifies the actual number of bytes returned in the message body, and the Content-Range header indicates the range of returned bytes.
