Lucas Santos

Posted on Mar 4, 2020 • Edited on Mar 18, 2020

The Complete Guide to Status Codes for Meaningful ReST APIs - The forgotten ones

#rest #webdev #statuscodes #internet

Photo by Kristina Tripkovic on Unsplash

In the last article we've seen a lot of the most common HTTP Status Codes and defined a lot of stuff, like what is a status code, how do they work and why are they so important. Now let's take a look at other status codes we don't see very much but they should be used more.

And also, we'll be continuing to use cats and dogs to illustrate our codes \o/

Summary

Summary
Codes we don't see very often, but we should
Take a Break

Codes we don't see very often, but we should

Now we're going to the perfect world, where we talk about those codes which are not seen too much in the wild but they're there and should be used more often.

200x

202 - Accepted

This is an async status code, it states that the request has been accepted but it does not say anything about the actual processing state of such request, neither about the result of that which might happen on another server. The server must provide, on a header or by any other means, a pointer to a status monitor that will present the user with the status of the request sent earlier.

When to use it: This is the classical "queue" situation when we have a resource that is meant to be queued for later processing. The 202 status code indicates that said resource has been accepted, so everything is fine with the request, but it cannot be processed now, but it'll be finished someday. This is often used for batch processing or some sort of CPU intensive operation, we send the request that has to be processed and, in return, we get a status monitor link. Azure Cognitive Services has APIs like this.

204 - No Content

This is the simplest, yet the most unused status code. It just means that everything is ok, but there's nothing to say about it...

When to use it: I prefer to use it on DELETE requests since these kinds of requests do what they should do and nothing more. For instance, DELETE /user/1234 should delete the user, most people return a 200 status code, but this code implies that some answer would come with it, on a DELETE statement that's not true, we don't have anything else to say about it, the resource was just... Deleted...

205 - Reset Content

So... I didn't find a cat or dog image to put here and illustrate this code... BUT! The 205 code is defined in the RFC7231 and it states one of the most used things in the past – and present – postbacks! Synthesizing, it says that the request was processed and the user should request a page refresh to see that change.

When to use it: With SPAs this code has fallen into darkness nowadays since the last thing a SPA does is refreshing the page (after all, it's a single page application...). But, sometimes we're dealing with 202 cases and we could have a status monitor that showed us whether the process is done or not. If the resource is still processing, then it should return 202 otherwise, 205!

206 - Partial Content

This is my favorite status code, not only because we don't see it very often and it is so easy to understand, but also because it states clearly what it means and could help a lot if it was more used! The 206 code states that the content that is being sent back is not the whole content the server has on that resource. This is optionally a response to a Range header sent by the client. Azure Storage Services uses this header.

When to use it: I like to use it when performing search queries, for example, a GET /users query, this is obviously a list of users that I cannot return in full because it can weight a ton of bytes, so I paginate it. The first time a user requests it, the server will answer a 206 with a custom header I like to call X-Content-Range which has from-to/total, next up we have two options:

The user requests GET /users?page=2
The user requests GET /users with a header Range: <page number>

Then the server will answer it with 206 until there are no more pages, on the last page it'll answer 200, if the user tries to access a page outside of the range I return a 204 (if I don't want to cause panic), or a 416.

300x

303 - See Other

The See Other status code refers to the second part of a POST or PUT request when we create the resource and it is accessible through another URI, then the server should send a Location header stating where the new resource can be found.

When to use it: You can either use the 202 status code when you're talking about a document that is created but the user does not need to see it or the application does not need to take the user to the resource page. In all other situations, use 303.

304 - Not Modified

The "not modified" status code is a bit complicated due to its possibilities, however, according to the default statement of its definition, this status code should be returned when the client issues a request with the If-Modified-Since or If-None-Match headers and the server does not find any modified resources.

When to use it: I like to use it differently, normally I return a 304 if the document altered by a PUT or a PATCH request did not suffer any modifications, this is ratter useful to define if we should reload or not the page.

This is a personal opinion, I know this is not how the 304 code is intended to be used, but it serves me very well like this.

307 - Temporary Redirect

This status code is pretty much the same as 302, the only difference is that the 302 allows for HTTP method switching between calls, this means I can perform a GET request on the first endpoint, receive a 302 and then perform a PUT on the specified endpoint returned by the server. With 307 this is forbidden, you must perform the request with the same method.

When to use it: Same cases as 302, but more strict (I'd use it instead).

308 - Permanent Redirect

This status code is defined on the RFC7538, it's the same case as 307 but instead of replacing the 302, it replaces the 301, all other information is exactly the same.

When to use it: Same cases as 301, but more strict (I'd use it instead).

400x

409 - Conflict

This status code can be seen sometimes around the Web, but I wish it was more present... The 409 code indicates a conflict in the resource state, this can be caused due to a simultaneous update or if you are trying to insert something that is already there.

When to use it: I generally use it when doing POST requests, if the resource already exists I return a 409, for example, a user with the same email address is being registered, this is a conflict in the database.

413 - Request Entity Too Large

413 status codes are the ones that tell us that we're trying to send something way bigger than expected to our server. This status code is mostly used on requests with long bodies or very heavy requests. Azure Storage Services also uses these responses when creating or editing new blobs.

When to use it: Mostly used when the request has a body, on POST, PUT and PATCH methods. The most common use case is image upload if the image is bigger than the server is willing to process.

415 - Unsupported Media Type

This one is pretty straight forward too. Unsupported Media Type is used when the server does not support the Content-Type of the incoming request. Once again, storage APIs like Azure end up using it a lot when creating blobs

When to use it: Again, the image upload case, let's imagine we have a document being uploaded as PDF, but we only accept JPEG, this would return 415.

This is also a great representation of why we should not use 400 code for everything

422 - Unprocessable Entity

This status code is defined on the RFC4918, and it is the main reason why I wrote this article. Most people use 400 status code when the payload of a request is wrong, which means that is a bad request, but the problem is not in the request itself, it is in the payload, hence why 400 should not be used on these cases, instead, we should use 422 to say that the request is good, the server can understand it, but cannot process it due to a wrong sent entity.

When to use it: Validation errors, period. If your payload does not match a validation pattern, let's say, the email field is not a valid email, then this entity is not processable, thus 422.

Take a Break

Now we've reached the end of section two! In the last article, we'll be explaining other status codes that are either unused or have just ended up forgotten in the swamps of the Internet!

See ya!