Exploring HTTP methods and status codes

HTTP provides various HTTP methods. However, you are primarily going to use only five of them. To begin with, you want to have Create, Read, Update, and Delete (CRUD) operations associated with HTTP methods:

• POST: Create or search
• GET: Read
• PUT: Update
• DELETE: Delete
• PATCH: Partial update

Some organizations also provide the HEAD method for scenarios where you just want to retrieve the header responses from the REST endpoints. You can hit any GitHub API with the HEAD operation to retrieve only headers; for example, curl --head https://api.github.com/users.

Note

REST has no requirement that specifies which method should be used for which operation. However, widely used industry guidelines and practices suggest following certain rules.

Let’s discuss each method in detail.

POST

The HTTP POST method is normally what you want to associate with creating resource operations. However, there are certain exceptions when you might want to use the POST method for read operations. However, it should be put into practice after a well-thought-out process. One such exception is a search operation where the filter criteria have too many parameters, which might cross the GET call’s length limit.

A GET query string has a limit of 256 characters. Additionally, the HTTP GET method is limited to a maximum of 2,048 characters minus the number of characters in the actual path. On the other hand, the POST method is not limited by the size of the URL for submitting name and value pairs.

You may also want to use the POST method with HTTPS for a read call if the submitted input parameters contain any private or secure information.

For successful create operations, you can respond with the 201 Created status, and for successful search or read operations, you should use the 200 OK or 204 No Content status codes, although the call is made using the HTTP POST method.

For failed operations, REST responses may have different error status codes based on the error type, which we will look at later in this section.

GET

The HTTP GET method is what you usually want to associate with read resource operations. Similarly, you must have observed the GitHub GET /licenses call that returns the available licenses in the GitHub system. Additionally, successful GET operations should be associated with the 200 OK status code if the response contains data, or 204 No Content if the response contains no data.

PUT

The HTTP PUT method is what you usually want to associate with update resource operations. Additionally, successful update operations should be associated with a 200 OK status code if the response contains data, or 204 No Content if the response contains no data. Some developers use the PUT HTTP method to replace existing resources. For example, GitHub API v3 uses PUT to replace the existing resource.

DELETE

The HTTP DELETE method is what you want to associate with resource deletion operations. GitHub does not provide the DELETE operation on the licenses resource. However, if you assume it exists, it will certainly look very similar to DELETE / licenses/agpl-3.0. A successful DELETE call should delete the resource associated with the agpl-3.0 key. Additionally, successful DELETE operations should be associated with the 204 No Content status code.

PATCH

The HTTP PATCH method is what you want to associate with partial update resource operations. Additionally, successful PATCH operations should be associated with a 200 OK status code. PATCH is relatively new as compared to other HTTP operations. In fact, a few years ago, Spring did not have state-of-the-art support for this method for REST implementation due to the old Java HTTP library. However, currently, Spring provides built-in support for the PATCH method in REST implementation.

HTTP status codes

There are five categories of HTTP status codes, as follows:

• Informational responses (100–199)
• Successful responses (200–299)
• Redirects (300–399)
• Client errors (400–499)
• Server errors (500–599)

You can view a complete list of status codes at MDN Web Docs (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) or RFC-7231 (https://tools.ietf.org/html/rfc7231). However, you can find the most commonly used REST response status codes in the following table:

HTTP Status Code	Description
200 OK	For successful requests other than those already created.
201 Created	For successful creation requests.
202 Accepted	The request has been received but not yet acted upon. This is used when the server accepts the request, but the response cannot be sent immediately, for example, in batch processing.
204 No Content	For successful operations that contain no data in the response.
304 Not Modified	This is used for caching. The server responds to the client that the resource is not modified; therefore, the same cache resource can be used.
400 Bad Request	This is for failed operations when input parameters either are incorrect or missing or the request itself is incomplete.
401 Unauthorized	This is for operations that have failed due to unauthenticated requests. The specification says it’s unauthorized, but semantically, it means unauthenticated.
403 Forbidden	This is for failed operations that the invoker is not authorized to perform.
404 Not Found	This is for failed operations when the requested resource doesn’t exist.
405 Method Not Allowed	This is for failed operations when the method is not allowed for the requested resource.
409 Conflict	This is for failed operations when an attempt is made for a duplicate create operation.
429 Too Many Requests	This is for failed operations when a user sends too many requests in a given amount of time (rate limiting).
500 Internal Server Error	This is for failed operations due to server errors. It’s a generic error.
502 Bad Gateway	This is for failed operations when upstream server calls fail, for example, when an app calls a third-party payment service, but the call fails.
503 Service Unavailable	This is for failed operations when something unexpected has happened at the server, for example, an overload or a service fails.

We have discussed the key components of REST, such as endpoints in the form of URIs, methods, and status codes. Let’s explore HATEOAS, the backbone of REST concepts that differentiates it from RPC style.