HTTP Standards

Have you ever been testing an API and gotten involved in a dispute about what a response code should be?  Perhaps you witnessed a disagreement between two developers, or perhaps a developer was insisting the response code should be one thing and you thought it should be something different.  You might have gone to Stack Overflow to see what others think, and discovered people referencing something called an RFC.  

RFC stands for “Request for Comments”.  The RFCs related to HTTP protocols are produced by the ISOC: the Internet Society.  The Internet Society consists of tens of thousands of members, a staff, and a board of trustees.  They produce the standards that most developers use when developing websites and web applications, and those standards are written up in the form of RFCs.  

The first HTTP RFC was created in 1996, and RFC 2616, the most recent RFC that discusses response codes, was created in 1999.  These RFCs are surprisingly easy to read!  Let’s take a look at some of the contents of RFC 2616 and see how we can apply them to real-life scenarios.

Responses to POST requests:

In section 9.5, the RFC states “The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either 200 (OK) or 204 (No Content) is the appropriate response status, depending on whether or not the response includes an entity that describes the result.” So when you are doing a POST that doesn’t create a new resource, such as a request that checks for the existence of a resource, you could use a 200 or a 204 response code. But if your POST is returning a response body, you must use the 200 response code rather than the 204 response code, because the 204 response code cannot include a response body.

Responses to PUT requests:

In section 9.6, the RFC says “If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.” So as with the POST request, if you are modifying a resource and not returning anything in the body of the response, you could use a 200 or a 204 response code. But if you were returning something in the response body, you’d definitely want to use a 200.

Responses where the user is not allowed access to a resource:

Section 10.4.4 says of a 403 “Forbidden” response code: “The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity.  If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.” So if your user does not have permission to view a resource, and you don’t mind if the user knows that the resource exists, then you can use a 403 response code. But if you don’t want the user to even know that the resource exists, because perhaps that might give a malicious user too much information, then you’d want to return a 404 so that all they’d know was that the resource was not found.

Hopefully these examples have shown how useful the HTTP RFC documents can be. So the next time you are testing an API and you’re wondering if you’re seeing the right response code, try going to the source!