This week I had the honor to give a training to some of the newly started young professionals in our organisation. The topic of the training was API design in ASP.NET Core. During this training we discussed multiple topics and a lot of interesting questions were raised. I'll try to tackle some of them with a blog post.
The question I try to tackle today is...
What is idempotent in REST?
An important aspect when building REST API’s is the concept of ‘idempotency’. ‘Idem…what?’ I here you thinking.
Let’s ask MDN for an explanation:
An HTTP method is idempotent if an identical request can be made once or several times in a row with the same effect while leaving the server in the same state. In other words, an idempotent method should not have any side effects — unless those side effects are also idempotent. Implemented correctly, the GET, HEAD, PUT, and DELETE methods are idempotent, but not the POST method. All safe methods are also idempotent.
That explanation brings us to a second question, what are safe methods in REST?
MDN again:
An HTTP method is safe if it doesn't alter the state of the server. In other words, a method is safe if it leads to a read-only operation. Several common HTTP methods are safe: GET, HEAD, or OPTIONS. All safe methods are also idempotent, but not all idempotent methods are safe. For example, PUT and DELETE are both idempotent but unsafe.
Here is an overview:
| HTTP method | Safe? | Idempotent? |
| GET | yes | yes |
| OPTIONS | yes | yes |
| HEAD | yes | yes |
| POST | no | no |
| DELETE | no | yes |
| PUT | no | yes |
| PATCH | no | no |
Why is this important?
The answer is predictability. Developers that consume our API might expect that it follows the rules above. They might make certain technical decisions in their code assuming that the endpoints we provided them would work as per the standards. So knowing this will help us design our API endpoints that are compliant with industry standards, making lives easier for the people who use those APIs.
Another reason is reliability. You know when it is safe to implement some retry logic in your client without causing side effects. A library that can help you implement this is Polly.
