REST API Best Practices: HTTP Status Codes and You, Part 2(xx) - Status 200; Success!


Ah, the HTTP Status Code 200 series. Request sent by client, received by server, understood and processed, and a response has been sent. He shoots he scores, GOALLLLLLLL! The status code 200 series is the "Pass GO, Collect 200 Dollars" of HTTP Responses, this is the result for which we strive.

In this part of the series, I will cover some of the major HTTP 200 series response codes and how they can be used as part of an effective REST API strategy. Do note, that I will not cover them all here, but I want to touch on some of the ones you may already know, and some you may not know, but might easily start to use in API development process.

So with that, let's start at the very beginning, a very good place to start!

HTTP Status Code 200 - OK

What it means: Success! Everything worked out.
What content to expect returned: This largely depends on your request verb. For example, a GET request might return the requested resource, such as a JSON formatted response. A POST request to create a new resource may respond back with an "OK" to indicate success.

So, this should work for all my good REST API responses, right?

This is a great and the right way to start, associating a status 200 with a successful API call. The biggest flaw I see here is when people use a 200 to relay any information or status back, including failures. Often people seem to associated a 200 with a successful processing of the request, even if there are issues such as content not being found, failure to resolve resource IDs, and so on. Just because the application does not error out and can provide a response, does not mean a 200 is the proper response code! With that said, most developers likely may know what a 200 is all about, and the goal here is to expand horizons, so let's see what else there is in the 200 set that might make our APIs higher quality.

TLDR: Request understood and successfully processed? Default to a 200.


HTTP Status Code 201 - Created

What it means: Success, everything worked out and we created new resource successfully.
What content to expect returned: This status code is tailored to respond with an acknowledgement to a POST request to indicate the request has been fulfilled and a new resource has been created.

Hey wait a sec, you said that a 200 POST response could be used right up there!

...and so it can. What we are exploring here is expanding on the basic, default options to provide a better, more functional, and more feature rich API. A 201 is specific to responding that a resource was created. How might a developer use this? Say you have a light weight mobile application, where you want to keep processing to a minimum, limit total API calls back and forth, and to consume as little bandwidth as possible. If you were to send a POST request to create a new resource and simply respond with a generic 200 - OK, this may indicate success, but little else. A 201 specifically clarifies for a developer the intended "Create Resource" operation was executed successfully, and it can be tailored to supply specific information, such as the newly created resources ID. With this information for example, an application could see a 201 with the ID, saving several calls to search for the new resource on the remove system, and immediately redirect a user to that new resource by orchestrating logic based off the 201 status code. Think of not only the time, bandwidth, and resource usage this saves, but also the value to the end user experience. What if your APIs supported this, but a competitors did not?

The new resource ID could be returned as an independent header, it might be contained in an easy to use for redirection "Location" header, or perhaps in the body of a response message that may have other details as well (such as created resource attributes - eg alias). While a simple 200 OK success response may be sufficient, if the client wishes to use the new object or verify the values in its creation, it needs to know the new objects ID/location. The new header value (for example) can give a means to immediately ascertain this value (not tedious searching) for programmatic use, or the message body can contain a clickable link to support end client ease of use.

TLDR: If a new resource is created, a 201 can greatly enhance the end user experience in place of a 200.


HTTP Status Code 202 - Accepted

What it means: A request has been accepted by the processing system, but has not yet been processed. Results will only be realized after an asynchronous operation occurs.
What content to expect returned: Potentially a simple 201, though more information can be provided, such as a location in the response body to indicate where a user could monitor status, or a reference operation ID.

So you submit a request and get back a generic 200 - OK. That means your request was processed, right?

Not always! There are many reasons a backend service may not process your request immediately. Maybe it is resource constrained, so it queues up requests to process them over time. Maybe you have a throughput limit and your SLAs have been reached. Perhaps there are QOS items as play, and the service you are submitting to is not a priority channel. Maybe there is a manual adjudication process before submission. Whatever the case, there are times when your request may not be processed immediately, even if the submission was successful. A generic 200 OK message would not relay this information successfully.

How might this code help developers? Information is power, and these extended HTTP Status Codes all provide power for developers to better orchestrate operations and provide a better user experience. Simply being able to provide feedback that an operation is queue has great value, but this code can be expanded to really provide real value as well. For example, if a process ID is supplied, an application could collect this and build a "Queued" dialog for user to review. Using this information, it could periodically request status updates against a resource and notify users when operations are complete, or simply update a running status within an application. Perhaps the most powerful use of this status code is simply providing information that an operation was received, but not yet completed. Simply knowing and being aware of this is hugely helpful both to prevent time waste from things like trying to discover or access a resource that has not yet been created, or to ensure users monitor the status of an operation to ensure eventual success.

TLDR: 202 let you know your request was good, but the outcome is pending. Stay tuned!


HTTP Status Code 204 - No Content

What it means: Request received, processed, all good here!
What content to expect returned: None!

I assume most people reading this have been on a VOIP call, virtual meeting, etc. at some point in time. Ever hit that awkward silence when someone stops talking and you are waiting for them to continue or finish, until you hear "Oh, that's all!".

This status code is that awkward silence breaker. It is used to express that your request was accepted and processed, and the server is intentionally not sending a response. For example, there would be nothing to return from processing a DELETE request on an element. No new resource ID, no operational ID to indicate your request is queued, but you still want an acknowledgement back. This is far more informative than a simple 200 saying "something happened, it wasn't bad!", and can give further information to add a level of assurance of operational success, and allow for some next level operation to kick off.

Another use case might be that an old set of functionality was removed and is no longer present. What about a 300 series redirect though? This assumes there is new or different content to point to. Perhaps the old content was simply removed. What about a 404 then? This certainly means the content is not present, but that could be for a number of reasons, such as your client simply pointing to the wrong location (we all fumble finger paths on occasion!). In the context of this use case, a 204 very clearly says, "I get what your after, but I have nothing for you".

TLDR: If an operation was successful, but you have nothing to return, say so with a 204 rather than just saying "OK!".


HTTP Status Code 206 - Partial content

What it means: Here's what you asked for, part of it anyways.
What content to expect returned: Part of a resource requested by a GET request.

Often we find that users do not need an entire resource returned. You might see this for example in search results that return the first twenty items, with next or forward buttons and so on. Especially when it comes to mobile applications, we often want to limit the amount of data we return to a client, due to intermittent connectivity, slower connections speeds, and simply to be cognizant/respectful of data plan limitation. You may have seen this concept show up in requirements as "pagination".

This is where the 206 status code can come in real handy. This code is used to indicate to a client that only a partial set has been returned. Where a simple 200 does not provide this insight, a 206 allows a developer or application to know there is something more. Often, we will see this status code used in conjunction with a few different headers, such as a "Range" header on GET requests to indicate the data set a client wants returned, the "Accepted-Ranges" header on responses to indicate how the set can be accessed, and the "Content-Range" header on responses to specify what is being returned.

This status code, in conjunction with these headers, can allow an application to inform a user that a partial data set is being submitted, what range is being shown, and what ranges there are to select from.

TLDR: Here ya go boss, oh by the way, there is more where that came from!


There are more status codes in the 2xx range as well, but this sample provides some easy to use and powerful codes that can be a useful and differentiating factor for your API. These help to empower developers to provide a more autonomous and powerful application, and a better end user experience. If your organization is using just a 200 today, it is worth an investigation to see if these could add value to your REST APIs. Many of these can even be implemented without refactoring backend resource code by add logic to an abstraction layer.

Comments

Popular posts from this blog

Firewall, IDS, IDP, WAF, API Gateway: Choose Your Shield

API Security - The Next Generation with Elastic Beam