Idempotent is a funny word when used outside of the context of development. In fact, it's a term that comes from mathematics. It describes an element that can be operated on more than once and produces the same value every time. For example, the operation, 1 * 1, in traditional multiplication will always produce 1.

Within the world of development, the definition is almost the same.

For a microservice to be idempotent it must produce the same output if given the same inputs. Or in other words, it is idempotent if it's logic can be invoked more than once and produce only one side effect.

Let's explore this idea of one side effect per unique invocation.

One side effect per unique call

Take our 1 * 1 example from up above, our service might take two inputs n1 and n2 and return n1 * n2.

function runMultiply(n1, n2) {
  return n1 * n2;
}

The side effect here is the multiplication operation, the logic of our service. In its current state, this side effect happens every time runMultiply gets called. Even if our inputs remain the same, n1 = 1 and n2 = 1, we still run our operation n1 * n2 and return the value 1. Our service is idempotent, but is it producing one side effect per unique call?

By our most recent definition, no it's not. For a simple multiplication service like this one, it's not the end of the world. It's not creating any new resources, updating existing ones, or performing a complex algorithm. So running the logic again for a duplicated request isn't going to hurt anything.

Does idempotency imply exactly-once semantics? No.

As we saw with our multiplication example, we can have an idempotent service that does not have exactly-once semantics. This tends to happen when the service is stateless. They take some inputs and performs a stateless operation as we saw with our runMultiply.

Let's take a look at an example that illuminates the need for exactly-once semantics.

Say our microservice was responsible for creating a Person record in our database. The inputs to our service might be a name, address, and phone number. The first time our service gets invoked, we are going to create a new Person record for this name, address, and phone number combo.

function createPerson(name, address, phoneNumber) {
  const person = { name: name, address: address, phoneNumber: phoneNumber };
  // insert person into database
  return person;
}

If we did nothing else to this service, is it idempotent?

It's not. A second invocation with the exact same inputs (name, address, phone number) would cause another new Person to get created. This service will create duplicate people if invoked more than once with the same inputs.

The fix to make it idempotent is to check if there is already a Person with these values. If so, don't create a new one and return the person that is already present. If there isn't an existing object, create the new one and return success.

This is guaranteeing that exactly one side effect will happen. In other words, exactly one person will be created for each unique combo of name, address, and phone number.

Benefits of Idempotent

So what does idempotent unlock for us that we would otherwise be missing out on? There are a lot of benefits realized when our services are idempotent. But let's focus on three key ones.

1. Resilient: We have the ability to replay any invocations with the guarantee that a duplicate invocation won't produce a new side effect. This is huge in all types of systems because it means that if an error occurs we can simply retry the invocation.

2. Parallel Processing: An often overlooked benefit, we can process multiple invocations in parallel. If one of them fails, that's OK because we're resilient and can retry it.

3. Data Consistency: By guaranteeing exactly one side effect per unique invocation we can guarantee that our data is consistent. Meaning we don't have duplicate records or malformed data from incomplete invocations.

Resiliency is the key benefit to hone in on here. By being able to retry failed invocations we have unlocked a new world of scalability and performance. In distributed systems where dozens of microservices are interacting with one another having resiliency baked in is a huge win.

Conclusion

Idempotent sounds complex and a bit cumbersome. Its implementation can be complicated but the core idea is sound. Build services that can handle duplicate invocations while still only producing one side effect. If we keep the definition in mind as our guiding light we can refer to it as we are implementing a new service or updating an existing one.

Exactly-once semantics allows us to build systems that are resilient to failures. This is because a single invocation acts as a transaction between the service and the client. If this invocation is new, the service will execute its full logic. If this invocation is not new, the service will still succeed but not produce a second side effect.

Want to check out my other projects?

I am a huge fan of the DEV community. If you have any questions or want to chat about different ideas relating to refactoring, reach out on Twitter or drop a comment below.

Outside of blogging, I created a Learn AWS By Using It course. In the course, we focus on learning Amazon Web Services by actually using it to host, secure, and deliver static websites. It's a simple problem, with many solutions, but it's perfect for ramping up your understanding of AWS. I recently added two new bonus chapters to the course that focus on Infrastructure as Code and Continuous Deployment.

I also curate my own weekly newsletter. The Learn By Doing newsletter is packed full of awesome cloud, coding, and DevOps articles each week. Sign up to get it in your inbox.