RESTing: Part II - Répondez s'il vous plaît (Response Codes)

Those 3-digit numbers, the server generates to acknowledge all the requests, good, bad or unauthorized, are HTTP status codes.

For any website you visit, a request is sent to the server and the server responds with a response and HTTP status code. For all happy conversations, the server responds with 3 digit number starting with 2; for all rejected requests, the response sent has code starts with 4 or 5. It’s like they’re having a very mature but digital conversation. Ex: 200 means OK (request is ok and accepted) or 404 means the resource you are looking for is NOT FOUND or 500 means something went wrong on the server side INTERNAL SERVER ERROR (the complete list can be found here)

As a developer, It is our responsibility, to use the correct code in order to keep sanctity. Not only the first digit but all 3 digits are important to convey a proper message. Ex: Using HTTP 200 OK when the resource is created successfully is not enough to say the server is happy. Instead, 201 CREATED should be used. HTTP 400 BAD REQUEST should not be used when the server denied the request because the path parameter is bad. 404 NOT FOUND should be used for non-existing path parameters. In the same way, 404 NOT FOUND should not be used when a value in the body is incorrect and does not exist. And last 500 INTERNAL SERVER ERROR should not be thrown just because we do not know what else to return.

So how to use these codes? For now, here is a small snippet of the success codes for the API endpoints we created in the previous post (resources and API naming convention) -

GET    /books        200 OK or 204 NO CONTENT
GET    /books/{id}   200 OK
POST   /books        201 CREATED
PUT    /books/{id}   200 OK
PATCH  /books/{id}   200 OK
DELETE /books/{id}   200 OK or 204 NO CONTENT

Not always we are returning 200 to express the success. 201 CREATED and 204 NO CONTENT is also the common successful status codes used.

My team decided on these guidelines, which I would like to share with you. This can help you give some ideas to create your team's coding agreement for HTTP response codes. The following sections are categorized by HTTP methods, and all possible endpoints are used with successful and failed results. One of our favourite /books endpoints is used for reference. Let's begin...

GET

Possible endpoints -

GET    /books        
GET    /books/{id}   

On a successful GET request, the server must return a collection of objects or an empty collection or a single object with response codes as below -

GET    /books        
GET    /books/{id} 
GET    /books?active=true

200 OK       // when a single book object or collection is returned

GET    /books 

204 NO CONTENT // when an empty collection is returned

GET    /books?active=false

204 NO CONTENT // when an empty object is returned and the query parameter is correct

On failed GET request, the server must return a collection of generic error objects with response codes as below -

GET    /books        
GET    /books/{id} 

401 UNAUTHORIZED  // when the token is expired or incorrect
403 FORBIDDEN     // when do not have sufficient rights

GET    /books/{id} 

404 NO FOUND     // when id is invalid

GET    /books?active=1234
GET    /books/{id}?active=testingtesting123

422 UNPROCESSABLE CONTENT // when the query parameter is incorrect

POST

Possible endpoints -

POST   /books        201 CREATED

On a successful POST request, the server must return a new object that resembles with request object with the addition of the id property and the response code should be 201 created. Response should contain "Location" header pointing to url that can be queries to get the resource.

On failed POST request, the server must return a collection of generic error objects with response codes as below -

POST    /books

400 BAD REQUEST     
// when data is missing or incorrect in the request object. Ex: email address invalid or missing mandatory book name

401 UNAUTHORIZED  // when the token is expired or incorrect

403 FORBIDDEN     // when do not have sufficient rights

409 CONFLICT       // when the object is duplicated

PUT and PATCH

Possible endpoints -

PUT    /books/{id}   200 OK
PATCH  /books/{id}   200 OK

On a successful PUT/PATCH request, the server must return a new object that resembles with request object with the new values and the response code should be 200 OK. PUT should accept the entire object and replace old values with new values. While PATCH should accept partial object and replaces only values included in the request object the other values should be similar to old values.

On failed PUT/PATCH request, the server must return a collection of generic error objects with response codes as below -

   
PUT or PATCH    /books/{id} 

401 UNAUTHORIZED  // when the token is expired or incorrect

403 FORBIDDEN     // when do not have sufficient rights

404 NO FOUND     // when id is invalid 

PUT            /books/{id} 

400 BAD REQUEST     
// when data is missing or incorrect in the request object. Ex: email address invalid or missing book name

PATCH          /books/{id} 

400 BAD REQUEST     
// when data is incorrect in the new request object or trying to remove mandatory data from the old valid object. Ex: email address invalid or update book name to blank

DELETE

Possible endpoints -

DELETE    /books/{id}   204 NO CONTENT

On a successful DELETE request, the server must return an empty object with response codes 204 NO CONTENT indicating resource deletion is successful.

On failed DELETE request, the server must return a collection of generic error objects with response codes as below -

DELETE    /books/{id} 

401 UNAUTHORIZED  // when the token is expired or incorrect
403 FORBIDDEN     // when do not have sufficient rights
404 NO FOUND     // when id is invalid

HEAD

Possible endpoints -

HEAD    /books        
HEAD    /books/{id}   

The HEAD method is identical to GET, with the difference that it should not return a message body in response. Metadata like headers and response code should be included.

To see the response code please check to GET responses here. Please note HEAD is implicitly applicable to all GET endpoints.

This method is used to find out if the resource is valid, accessible, or has been modified recently. Ex: 404 NOT FOUND suggests that the resource does not exist while 200 OK means it does. The HEAD method is not just used to verify if the resource exists and is accessible, but is also used to check whether an entity previously cached through the GET method has been modified based on headers like content-length, etag, or last-modified. The response of HEAD is cacheable just like GET this helps its re-usage for comparing the entity's state.

OPTIONS

Possible endpoints -

OPTIONS    /books        
OPTIONS    /books/{id}
204 NO CONTENT 

The OPTIONS method should give information about what HTTP methods are allowed for the given endpoint using "Allow" header. For successful response 204 NO CONTENT response should be returned. This response should not be confused with resource does not exists.