table of Contents
- Interface idempotency meaning
- Interface complies Idempotence what use
- Such as power and security of HTTP methods
- How to design the interface complies idempotency
- Written in the last
Interface idempotency meaning
Idempotence originally meaning in mathematics, is an expression of the N-th conversion with the results of a linear transformation of the same.
The RESTFul API in idempotency refers to invoke a method once or N times affect the outcome of the resources generated are the same, require special attention are: idempotency here refers to the impact of the results of the resources generated, instead of calling HTTP method returns the result.
For example, the GET method RESTFul API is the query resource information, will not have an impact on resources, so it is in line with idempotency, but the results of each call GET method returns may be different (probably a property resources GET method before calling other methods have been changed).
In fact, API idempotent in a distributed architecture not only for RESTFul interface, but the interface is suitable for all types, in order to ensure when calling once or N times interfaces affect the outcome of the resources are the same.
Interface complies Idempotence what use
Idempotency interface ensures that regardless of the impact once or N times for resources calls are the same, which in some cases is very useful.
For example, there is such an interface method: pay (long account, int money ), the method used for bank debit card payments, account parameters for the account ID, money is deducted from the amount of money needed. When the user clicks the button to pay from the web, you need to deduct the corresponding commodity prices from the designated account in the implementation logic of the method. If the payment operation has been performed successfully, but for some reason the response message to the client failed to return, this time to the user experience is not likely to be successful payment, if paid at this time click on the button again, then once again to execute the method the results may lead users to buy only one item, it took double the money, which of course is unreasonable. Entire process as shown below:
Of course, the above example scenario, a user in order to avoid duplicate payments, can be solved through other means, such as: distributed transaction, or prompt the user to give tips based on payment status and so on.
If, however, the introduction of a distributed transaction, it will bring the complexity of the implementation, but also will affect the interface performance; and to take prompt manner and not one hundred percent sure that the user does not duplicate payments, there are certain risks. And if the interface complies with idempotency, namely: an order for the same pay whether it is performed once or multiple payments, to ensure that both the service side will buckle first paragraph, then neither need to introduce the complexity of distributed transactions, but also from solve the problem of duplicate payments fundamentally, this is the interface complies idempotency of value.
All in all, the interface in line with idempotent can reduce the complexity of system implementation, and to ensure consistency of state resources.
Such as power and security of HTTP methods
Design of the interface used on the nature of the HTTP protocol RESTFul style method, therefore, the power of RESTFul interface method and the like refers idempotent HTTP method.
Common HTTP methods: OPTIONS (to obtain server information), HEAD (request the resource header information), GET (access to resources), POST (create a resource), PUT (update resource all the information), PATCH (updated resource section information), DELETE (delete resources). So, these idempotent HTTP methods and what kind of it?
In addition idempotent addition, the safety means does HTTP method to produce a modified resources.
The following is a commonly used method of power such as HTTP and safety summary:
| HTTP method name | Whether idempotent | Is it safe |
|---|---|---|
| OPTIONS | Y | Y |
| HEAD | Y | Y |
| GET | Y | Y |
| PUT | Y | N |
| DELETE | Y | N |
| POST | N | N |
| PATCH | N | N |
As can be seen from the above table, idempotent and security HTTP method is not the same concept, the following are idempotent and interpretation of a respective security method:
- OPTIONS methods are often used to get server information, and will not impact on the resources, nor will the resources be modified, so it is idempotent is safe; OPTIONS method is the most common scenario in cross-domain requests the browser, If the browser is launched API (whether it is the gET method or POST method) a cross-domain access, and then send the real business of gET or POST method sends an OPTIONS method before obtaining information from the server, the information obtained from the server returned know whether the request to support cross-domain access, in order to decide whether the next step to successfully send a real service request.
- HEAD method for the header information, a resource request will not affect the resources, nor will the resources be modified so that it is idempotent is safe.
- GET method is used to obtain resource information, although it may result returned is not the same each time, but the GET method itself does not have an impact on resources, it will not modify the resources RESTFul semantics in the GET method, so it is idempotent, also safe.
- PUT method represents the total amount of resources to update, so the call once or N times the results are the same, so it is idempotent, but not safe in RESTFul in semantics.
- The results DELETE method for deleting resources, calling once or N times are the same, so is idempotent, but not safe.
- POST method represents a new resource in RESTFul semantics, apparently invoked once with the results of invoking the N times different (call once a new one resource, call N times the new N resources), and therefore is not idempotent, while not to be safe .
- PATCH method RESTFul shows local updates in the semantic resources, we can not guarantee the same results call once call N times (eg: updated resource as an attribute of the number of calls in different variations), so it is not idempotent at the same time it is not safe.
How to design the interface complies idempotency
The key design of the interface is to ensure that power and other interfaces to be called either once or N times, the impact of its resources are the same.
Can be seen from the above summary idempotent HTTP methods, and PATCH POST method of the HTTP protocol is not idempotent nature (but we often use them in RESTFul interface), does that mean it can not be POST PATCH and methods designed to idempotency interfaces of it? The answer is clearly no. In the above example, the order ID can also be used as one method parameters, such as: pay (long account, int money , long order), so make sure that the server will only be paid once an order (order number is globally unique) , regardless of which method is called once or N times the results are the same, it ensures idempotency interface. Of course, the order number which is not in the scene, the interface may operate to generate a globally unique ID of the process number, process number and the ID as the parameter one of the methods, so that a process number to ensure that the server will only be executed once ID ensure the idempotency interface.
Compliance idempotent interface call flow is described as follows:
Written in the last
Although designed to meet Idempotence interface in some cases can reduce the complexity of the system (such as: the introduction of a distributed transaction can not), but the interface is not able to solve the problem by Idempotence in all occasions, when necessary still we need to introduce such a framework of distributed transaction processing. We do not bring the interface idempotency as a universal solution, but we try to consider in line with idempotency treatment is very valuable in the design of the interface.
[Reference]
http://blog.720ui.com/2016/restful_idempotent/ how to understand RESTful idempotency
https://www.cnblogs.com/weidagang2046/archive/2011/06/04/idempotence.html understand the power of HTTP and other sexual
https://sofish.github.io/restcookbook/http%20methods/idempotency/ RESTful manual