HTTP methods and features that SHOULD be understood by API design

This is the 12th day of my participation in Gwen Challenge. For details, see Gwen Challenge.

In the REST API design philosophy, we use HTTP verbs (methods) for specific operations on resources. Yesterday’s API Endpoint/Resource Naming Best Practices introduced endpoint naming. Today, we introduce HTTP methods that are often used in REST API design. Developers typically only use GET, PUT, DELETE, or POST, and HTTP officially describes 39 HTTP request methods and the scenarios for which each method fits. In this article, I introduce HTTP request methods and features commonly used in REST API design.

1. Obtain resources

The most familiar are GET and HEAD, which are used to GET resources in a specific way. This is the easiest method to understand and the most commonly used.

GET

The GET method is used to request a specific resource, and the GET request should only be used to GET data.

HEAD

HEAD reflects some of the functionality of the other method while unlocking more possibilities. The HEAD requests a GET response from a given resource without a response body, which may seem simple, but it allows greater flexibility to extend for other apis, such as the ability to pass the HEAD of a resource to another request to simulate a different request environment, which can be very helpful for testing and troubleshooting.

2. Modify resources

There are many ways to fundamentally change a resource, including placing a resource, replacing a target resource, or even updating the attributes associated with the resource.

PUT

PUT is sort of the opposite of GET. GET requests a specific resource, and PUT places the resource in a remote directory. It should be noted that with PUT, a resource is created when it doesn’t exist and overwrites when it does exist.

PATCH

PATCH is used to partially modify the target resource. In other words, when PUT places the resource in the target service, PATCH modifies the resource rather than replacing it, which is useful for updating files or versions.

3. Delete resources

DELETE the target resource. The usual response to the delete method is simply to revert to the OK status-the resource is deleted or not.

4. Create resources

POST is used to create a target resource and allows an attribute or entity to be submitted through the API.

5. Resources and environment

Not every change to a resource has to be a change to the content of the resource, and there are two methods that interact with the resource environment more than the resource itself.

TRACE

TRACE is a way to perform a message back test that allows you to view the path to the target resource and identify potential points of failure. This is a very powerful tool, although it can be simple, because it simply reflects the basic path of the resource.

CONNECT

CONNECT is a method for creating communication with a resource rather than directly interacting with the resource. CONNECT is used to establish a channel to CONNECT to the server of the target resource. The usual effect is to use the server as a springboard (proxy server), allowing the server to visit other web pages on behalf of the user, and then return the data to the user as it is.

idempotence

Idempotence is one of the important characteristics of HTTP methods. By definition, Idempotence means that one or more requests for a resource should have the same response result. According to the definition of idempotent, only GET, HEAD, PUT and DELETE are idempotent, while POST and PATCH are not.

security

Security is another feature of HTTP methods. Unlike idempotence, security methods do not change the state of the server at all. Only GET and HEAD are secure by this definition.

Here are the security and idempotency of the above methods:

Method names	security	idempotence
GET	is	is
HEAD	is	is
POST	no	no
PATCH	no	no
PUT	no	is
DELETE	no	is

conclusion

A deep understanding of these methods, their idempotence, and their security is fundamental to API design.