Alex - stock.adobe.com
The 5 essential HTTP methods in RESTful API development
While HTTP methods aren't inherently complex, developers still need to understand the core RESTful API HTTP methods and why they matter.
REST is the key to assuring that independently developed clients and servers can interact safely.
HTTP-based APIs integrate easily with RESTful web services but often seem illogical, overlapping and inefficient. There are many ways to use HTTP methods, plenty of which aren't compatible with RESTful principles, so it's important to review the HTTP API methods and understand how to use them appropriately.
Let's take a quick look at the main difference between resources and resource collections, and then examine the five fundamental HTTP methods those involved with RESTful API development should know, along with four additional methods that might be useful in more specialized applications.
HTTP resources vs. resource collections
An HTTP resource is comparable to a data file: Developers can read and update the resource's contents, and it is hosted on a server and addressable using a URL. A resource collection is a set of related resources similar to a set of related files.
The relationship between the resources within a collection hinges on the software that supports the collection -- specifically, that software's implementation. If the implementations don't assign some dictated order to client behavior, the resulting multiplicity can create mismatches and cause applications to break.
Method 1: POST
POST is the only RESTful API HTTP method that primarily operates on resource collections. When creating a subordinate resource in a collection, applying POST to the parent resource prompts it to create a new resource, associate it with the proper hierarchy and return a dedicated URL for later reference. However, remember that POST is not idempotent; using this method more than once will lead to inconsistent outcomes or results.
A significant benefit of POST is that it enables developers to define resources explicitly. This feature helps prevent teams from accidentally creating subordinate resources that pollute code, muddy references and cause applications to experience problems.
Idempotent vs. non-idempotent methods
An HTTP API design should never result in a client request that puts the server in an uncertain or unstable state, whether due to error recovery or software error.
A method is considered "safe" if it does not affect the state of a server; all such methods are also idempotent. A method is idempotent if the client can repeat the request, likely through software error or network error recovery, without the risk of the server entering a bad state. Of the five most common HTTP methods for RESTful API development, POST is not idempotent, and PATCH might or might not be, depending on whether its use is conditional. To make an API fault-tolerant, it's best practice to use idempotent methods where possible and to document the use of non-idempotent methods.
Method 2: PUT
The single-resource equivalent of POST is PUT, which updates a resource by replacing its content entirely. As a RESTful API HTTP method, PUT is the most common way to update resource information.
It's possible to create a resource with a PUT method, but this approach carries the risk of creating resources by accident. Applying PUT to a collection of resources replaces the entire resource collection, which usually isn't the intention.
Method 3: PATCH
PATCH is another HTTP method for updating resources. Rather than replacing resources, as the PUT method does, PATCH modifies resource contents. These modifications should generally be expressed in a standard format, like JSON or XML.
Much like in PUT, it's poor practice to specifically apply PATCH methods to a whole resource collection unless the intention is to update every resource it contains.
Method 4: GET
The most common HTTP method is GET, which returns a representational view of a resource's contents and data. Using GET in read-only mode is important, which keeps the data safe and the resource idempotent. GET should return the same results no matter how often the client uses this method unless another client modifies it in the interim.
A client might sometimes use the GET method to change the contents of a resource, but this is a precarious use. It's common to compromise a client's ability to PATCH a resource if the resource detects a change since the PATCH client last conducted a GET.
Method 5: DELETE
When a DELETE method targets a single resource, it removes that resource entirely.
DELETE implementations are typically somewhat inconsistent: The URL for the resource might remain available even if the actual resource is absent. In this scenario, it's possible the server or resource implementation still changes the state of the vanished resource using the URL and likely reacts differently to subsequent DELETE executions.
While it's certainly possible to use the DELETE method in a resource collection, it's generally best to avoid it because it deletes all contents.
Miscellaneous HTTP methods
In addition to the five main HTTP methods for RESTful API development, four additional methods can help organize and optimize HTTP API-based applications.
Though rarely necessary in typical client-server transactions, these methods can sometimes be helpful, like when developing applications that interact with servers that might support different client-server relationships or in situations where HTML content references multiple servers.
Method: HEAD
HEAD is a method for querying resource metadata on the server. Typical usage involves checking a resource's size or state before using it with another method. The response is the same as that of a GET, but the server doesn't return the message body.
Method: OPTIONS
OPTIONS returns a list of supported methods for the specified resource, which developers can use to tailor API access to the optimal set of available methods. OPTIONS is also valuable for cross-origin resource sharing (CORS) preflighting to determine whether a server would accept a method call for a cross-origin resource.
Method: TRACE
TRACE is useful for debugging and verifying API data format and content. It shows how the destination and intermediary servers handle an HTTP message by returning the message as it was received and generally consists of request headers.
Method: CONNECT
CONNECT requests a proxy establish a tunnel to a specified destination. It can allow HTTP to carry a session in another protocol, including relatively insecure protocols like SMTP and FTP. Its ability to encapsulate another protocol creates a security risk. As a result, developers should only use CONNECT when there is a map of safe request targets for CONNECT to reference.
Editor's note: This article was expanded and republished to improve the reader experience.
Tom Nolle is founder and principal analyst at Andover Intel, a consulting and analysis firm that looks at evolving technologies and applications first from the perspective of the buyer and the buyer's needs. By background, Nolle is a programmer, software architect, and manager of software and network products. He has provided consulting services and technology analysis for decades.
