How to understand idempotent [or HTTP idempotent]

How to understand idempotent

Understanding the Essentials

Idempotent is the interface of the system to the external commitment (rather than implementation), the commitment as long as the invocation of the interface succeeds,

The impact of external multiple calls on the system is consistent

. An interface declared as Idempotent will assume that an external call failure is the norm, and

There must be retries after the failure.

APIs that are declared idempotent have the same effect on the calling resource after multiple calls, or the result of a call to a single invocation, and the Idempotent API emphasizes security and does not cause errors in the system resources due to repeated calls, which are particularly important in financial services.

An HTTP Idempotent method is an HTTP method that does not have a different result, no matter how many times it is called. Whether you call it once or call it 100 times, 1000 times, the result is the same.

Take the example of the previous blog post.

   
   
    
    Get     /tickets       # Get ticket list
    
    get     /tickets/12    # View a specific ticket
    
    POST    /tickets       # Create a new ticket
    
    PUT     /TICKETS/12    # Update ticket
    
    PATCH   /TICKETS/12    # Update ticket
    
    DELETE  /TICKETS/12    # Delete Ticekt 12
   
   

HTTP Get Method

The HTTP get method, which is used to get the resource, no matter how many times the interface is called, the result is not changed, so it is idempotent.

   
   
    
    Get     /tickets       # Get ticket list
    
    get     /tickets/12    # View a specific ticket
   
   

Just querying the data does not affect the resource changes, so we consider it idempotent.

It is worth noting that idempotent refers to the effect on the result rather than the resource itself. How to understand it. For example, this HTTP GET method may get different returns each time, but it does not affect resources.

Maybe you'll ask if that's the case. Of course there is. For example, we have an interface to get the current time and we should design it as

   
   
    
    Get     /service_time # Gets the current time of the server
   
   

It does not have an impact on the resource itself, so it satisfies the idempotent nature.

HTTP Post Method

The HTTP post method is a non-idempotent method, because calls are made more than once, and new resources are generated.

   
   
    
    POST    /tickets       # Create a new ticket
   
   

Because it has an impact on the resource itself, each invocation has a new resource generation and therefore does not satisfy idempotent.

HTTP Put method

The HTTP put method is not idempotent. Let's see.

   
   
    
    PUT     /TICKETS/12    # Update Ticket 12
   
   

Because it directly replaces the data of the entity part with the resources of the server, we call it several times, only have the effect once, but have the same result HTTP method, so satisfy the Idempotent property.

HTTP Patch Method

The HTTP patch method is non-idempotent. The HTTP POST method and the HTTP put method may be better understood, but the HTTP patch method just updates some of the resources, how about non-idempotent?

Because patches provide entities that need to be parsed and executed on the server, depending on the definition of the program or other protocol, the resources on the server are modified. In other words, a patch request executes a program, and if repeated commits, the program may execute multiple times and the resources on the server may have additional impact, which can explain why it is non-idempotent.

Maybe you don't understand that yet. Let's give an example

   
   
    
    Patch   /TICKETS/12    # Update Ticket 12
   
   

At this point, our service side of the method of processing is, when called a method, update part of the field, the ticket record of the operation Record plus one, this time, each call to the resource is not changed, so it is likely to be a non-idempotent operation.

HTTP Delete Method

The HTTP Delete method is used to delete the resource, and the resource is deleted.

   
   
    
    Delete  /tickets/12    # Remove Ticekt 12
   
   

The invocation and multiple times have the same effect on the resource, so it also satisfies the idempotent nature.

How to design a high-quality restful API that complies with Idempotent http GET method vs HTTP POST method

Maybe you'll think of a face question. What is the difference between the get of an HTTP request and the Post method? You may be able to answer: The Get method submits the data through the URL, the data is visible in the URL, and the data is placed within the HTML header. However, we now look at the problem from the perspective of RESTful resources, the HTTP GET method is idempotent, so it is suitable as a query operation, the HTTP POST method is non-idempotent, so it is used to represent the new operation.

However, there are exceptions, and sometimes we may need to transform the Query method into an HTTP POST method. For example, an extra-long (1k) Get URL is replaced with the Post method because get is limited by the length of the URL. Although, it does not conform to idempotent, but it is a compromise scheme.

http POST method vs http Put method

For the HTTP POST method and the TTP put method, we generally understand that post represents the creation of a resource, and a put represents an update resource. Of course, this is the right understanding.

However, in fact, two methods are used to create resources, and the more essential difference is idempotent. The HTTP POST method is non-idempotent, so it is used to represent the creation of resources, and the HTTP put method is idempotent, which means that updating resources is more appropriate.

http Put method vs http Patch method

At this point, you see that there is another problem. Both the HTTP put method and the HTTP patch method are used to describe the update resources and what is the difference between them. Our general understanding is that put means updating all resources, and patch represents updating some resources. First of all, this is the first rule we abide by. According to the above description, the patch method is non-idempotent, so we also need to consider when we design our server's RESTful API. If we want to explicitly tell the caller that our resources are idempotent, my design is more inclined to use the HTTP PUT method.

    (end)
=