Coding Gems: Idempotency

How to Implement Safe and Idempotent Methods on the Server?

Implementing safe methods

In HTTP, safe methods are not expected to cause side effects. Clients can send requests with safe methods without worrying about causing unintended side effects. To provide this guarantee, implement safe methods as read-only operations.

Safety does not mean that the server must return the same response every time. It just means that the client can make a request knowing that it is not going to change the state of the resource.

Example, both the following requests may be safe:

# First request

GET /emp?symb=rajesh HTTP/1.1

Host: www.comviva.org

HTTP/1.1 200 OK

Content-Type: text/plain;charset=UTF-8

15.96

# Second request after 5 minutes

GET /emp?symb=rajesh HTTP/1.1

Host: www.comviva.org

HTTP/1.1 200 OK

Content-Type: text/plain;charset=UTF-8

16.10

Implementing idempotent methods

Idempotency matters most in the case of network or software failures. Clients can repeat such requests and expect the same outcome.

Idempotency guarantees clients that repeating a request have the same effect as making a request just once.

Idempotency of PUT

Example, consider the case of a client updating the price of a book.

# Request

PUT /books/poor-dad-rich-dad/price/us HTTP/1.1

Host: www.flipkart.com

Content-Type: application/x-www-form-urlencoded

val=14.95

Now assume that because of a network failure, the client is unable to read the response. Since HTTP says that PUT is idempotent, the client can repeat the request.

# Request

PUT /books/poor-dad-rich-dad/price/us HTTP/1.1

Host: www.flipkart.com

Content-Type: application/x-www-form-urlencoded

val=14.95

# Response

HTTP/1.1 200 OK

Content-Type: application/xml;charset=UTF-8

Idempotency of DELETE

The DELETE method is idempotent. This implies that the server must return response code 200 (OK) even if the server deleted the resource in a previous request.

However in practice, implementing DELETE as an idempotent operation requires the server to keep track of all deleted resources. Otherwise, it can return a 404 (Not Found).

# First request

DELETE /book/poor-dad-rich-dad/ HTTP/1.1

Host: www.flipkart.com

# Response

HTTP/1.1 200 OK

# Second request

DELETE /book/poor-dad-rich-dad/ HTTP/1.1

Host: www.flipkart.com

# Response

HTTP/1.1 404 Not Found

Content-Type: text/html;charset=UTF-8

<html>

...

</html>

Even when the server has a record of all the deleted resources, security policies may require the server to return a 404 (Not Found) response code for any resource that does not currently exist.

Methods in Rest Service

GET Method:

This method can be used only to retrieves data from the server.

Example: GET request to retrieve the emp with id 110 from Server.

GET /emp/110

POST Method:

This HTTP request type is usually used for creating an entity i.e. a resource without an id. Once the request is successfully created, an id of the newly created entity is returned as part of the response.

Example:

POST /emp/

PUT Method:

It is similar to POST, but used to update an existing entity. We need to pass the id of existing resource along with PUT request type.

Example:

PUT /emp/123

DELETE Method:

This method can be used to removes the resource from the server. Similar to PUT you need to pass the id of the resource to be deleted.

Example:

DELETE /emp/123

TRACE Method:

Provides a means to test what a machine along the network path receives when a request is made. As such, it simply returns what was sent.

HEAD Method:

This method is same as the GET method for a resource but returns only the response headers. Similar to the GET request, HEAD Is also idempotent i.e. no side effect on Server.

OPTIONS Method:

It allows a client to request information about the request methods supported by a service. The relevant response header is Allow and it simply lists the supported methods.

CONNECT Method:

Primarily, It can be used to establish a network connection to a resource (usually via some proxy that can be requested to forward an HTTP request as TCP and maintain the connection). Once established, the response sends a 200 status code and a “Connection Established” message.

Idempotency and Idempotent Methods

Idempotence is the property of certain operations in mathematics and computer science that can be applied multiple times without changing the result beyond the initial application.

The term was introduced by Benjamin Peirce in the context of elements of algebras that remain invariant when raised to a positive integer power and literally means "(the quality of having) the same power", from idem + potence (same + power).

From a RESTful service standpoint, for an operation (or service call) to be idempotent, clients can make that same call repeatedly while producing the same result.

Idempotent Methods in Rest Service:

GET, PUT, DELETE

Note: POST is not an idempotent method.

Two main categories of HTTP Methods:

1. Safe

2. Idempotent.

Safe Methods in HTTP

These are HTTP methods which don't change the resource on the server side i.e. READ ONLY methods.

Example: GET or a HEAD are safe methods, however, POST (POST /books/), PUT (PUT /books/123), or DELETE are non-safe.

Idempotent Methods in HTTP

These are methods which are safe from multiple calls i.e. they produce the same result for multiple calls. They change the resource in Server every time you call them but the end result is always same.

Example:

int x = 10;

This assignment operation is idempotent, no matter how many times you execute this statement, x will always be 10

++x; It is not idempotent because every time it will return the different. Since both examples are changing the value of i, both are non-safe methods.

HTTP Method	Idempotent	Safe
OPTIONS	yes	yes
GET	yes	yes
HEAD	yes	yes
PUT	yes	no
POST	no	no
DELETE	yes	no
PATCH	no	no

Idempotency is one of the important reasons to prefer the PUT method over POST to update any resource in REST service.

The problem with the POST method:

Suppose a client wants to update a resource through POST. Since POST is not an idempotent method, calling it multiple times may result in incorrect updates.

Let us suppose that our POST request may timeout, what will happen to the resource that. Is the resource actually updated or does the timeout happen during sending the request to the server, or the response to the client? Can we safely retry again, or do we need to figure out first what has happened with the resource?

By using idempotent methods like PUT, you don't have to answer this question, but we can safely resend the request until we actually get a response back from the server.

Coding Gems

Pages

Tuesday, 11 April 2017

How to Implement Safe and Idempotent Methods on the Server?

Methods in Rest Service

Idempotency and Idempotent Methods