API Series: HTTP Methods and Status Codes

As previously discussed, we based our API on REST to fully embrace and utilize the power of HTTP. However, with this comes certain responsibilities; after all, HTTP dictates specifications and guidelines that should be adhered to in order to properly work with the protocol. Two such items are HTTP methods and status codes.

The HTTP Specification

To ensure we understood exactly how and when to use certain methods and status codes, we spent quite a bit of time going through the actual HTTP specification, in particular those two areas. We kind of obsessed about it to be honest, but then again, we obsessed about all aspects of our API design. Many people say they have a RESTful API, yet under closer examination only take it about 80% of the way there. We wanted to be 100% RESTful, and the only way we could accomplish that was to truly understand those two sections of the HTTP specification.

HTTP Methods

Simply put, HTTP methods are actions to be taken by a web site and its underlying web server, and for the Znode API, we standardized on GET, POST, PUT, and DELETE to handle any request to all of our endpoints, as described below:

Method Description
GET Used for two scenarios – 1) retrieving a single object/resource or 2) retrieving a list of objects/resources.
Example: getting a product with ID 302 or getting a list of products for a particular category.
POST Used when creating a new object/resource.
Example: adding a new product to the store catalog.
PUT Used when updating an existing object/resource.
Example: updating the description and attributes for product with ID 302.
DELETE Used for deleting an existing object/resource.
Example: deleting product with ID 302.

HTTP Status Codes

Status codes, sometimes referred to as response codes, represent the result of a particular HTTP method. Status codes tell you whether or not the API call was successful, a key design principle in RESTful APIs. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate a server error.

Below are the status codes used by the Znode API and when they are used:

Code Description Method Usage
200 OK The request was successful. Returned when GET and PUT are successful.
201 Created The item sent in the request was successfully created. Returned when POST is successful.
204 No Content The request was successful, but there was nothing to return. Returned when DELETE is successful.
403 Forbidden API key was invalid or not supplied. Could happen on any request.
404 Not Found The requested item doesn’t exist. Returned when GET fails.
500 Internal Server Error Something went wrong processing the request. Returned when GET, POST, PUT, DELETE fails.

100% RESTful

We mentioned earlier that some people claim to be RESTful yet only make it about 80% of the way there. So what did we mean by that? Let’s discuss this with a couple examples.

Example 1. Creating a New Object

Let’s say an API has an endpoint that allows you to create a new object, in this case a product. And to create a new product, you must use the POST method, sending in the data used to create the product in the request body. In this case the endpoint is POST /products.

The problem is that most people get the response wrong when this call is successful. What they do is return a 200 OK status code along with the newly created object. This is incorrect. What they should do is actually return a status code of 201 Created and also populate the Location response header with the value of the URL of the newly created object.

Example 2. Deleting an Object

Let’s say an API has an endpoint that supports deleting an object, in this case a product. And to delete a product from this endpoint, you must use the DELETE method and put the product ID in the URL, as such: DELETE /products/302. So far, so good.

However, what many people do when this DELETE call is successful is return a 200 OK status. This is also incorrect. If the DELETE was successful, the resource at that endpoint no longer exists, thus, the correct status code should be 204 No Content, which says the call was successful but there is nothing to return.

Our API Gets It Right

The above two examples are what we mean by having an API that is 100% RESTful, and our Znode API handles those actual scenarios the way they should be handled.

Consistent and Predictable

What all of this ultimately comes down to is having an API that is consistent, because a consistent API is a predictable API, and predictability is one of the guiding tenets of our API design. You can be assured that when you create a new object in our API, you’ll get back a 201 Created status code with a Location header, and that when you delete an object you’ll get back a 204 No Content status code.