{"id":1965,"date":"2022-07-07T11:10:46","date_gmt":"2022-07-07T08:10:46","guid":{"rendered":"http:\/\/52.91.248.125\/idempotent-apis-tips-to-build-resilient-apps-2\/"},"modified":"2023-02-28T11:53:24","modified_gmt":"2023-02-28T09:53:24","slug":"idempotent-apis-tips-to-build-resilient-apps-2","status":"publish","type":"post","link":"https:\/\/www.orfium.com\/ja\/news\/idempotent-apis-tips-to-build-resilient-apps-2\/","title":{"rendered":"Idempotent APIs \u2014 Tips to build resilient apps"},"content":{"rendered":"\n
\"\"\/<\/figure>\n\n\n\n

Photo by Tim Mossholder<\/a> on Unsplash<\/a><\/p>\n\n\n\n

There is a question to which typically we, as Developers, kind of turn a blind eye.<\/p>\n\n\n\n

When was the last time your product had downtime? How did it affect your customers?<\/em><\/strong><\/p>\n\n\n\n

And why wouldn\u2019t we?<\/p>\n\n\n\n

We follow all the Agile processes, we go through multiple debates during the code review phase, we have automated and unit tests, we have QA teams that catch nasty bugs early, we write types on both Frontend and Backend, we use state-of-the-art tools, we do everything by the book. We trust that our code represents our best collective work.<\/strong> We expect it to simply work!<\/strong><\/p>\n\n\n\n

…<\/p>\n\n\n\n

…<\/p>\n\n\n\n

…<\/p>\n\n\n\n

Until it doesn\u2019t<\/em>.<\/strong><\/p>\n\n\n\n

<\/div>\n\n\n\n
\"\"
Photo by Elisa Ventur<\/a> on Unsplash<\/a><\/figcaption><\/figure>\n\n\n\n
<\/div>\n\n\n\n

API resiliency<\/strong> refers to the idea that we build APIs which are able to recover from failure. Failures can be caused by either our own or third-party service problems, server outages, DDoS attacks, network issues, and so much more. Frankly, there are innumerable reasons for which these failures occur. What\u2019s more important is how you recover from them and ensuring they do no lasting damage. Let\u2019s talk about an example.<\/p>\n\n\n\n

Case: Artist wants to upload his song to our App<\/strong><\/h3>\n\n\n\n

We have created an App <\/strong>that has a Client <\/strong>and an API Server.<\/strong><\/p>\n\n\n\n

In our case, let\u2019s say that our user is an artist<\/strong> who is trying to submit their<\/strong> song<\/strong> to our platform, so we can collect royalties on their behalf.<\/p>\n\n\n\n

We wrote a POST HTTP method that creates the song in the Server\u2019s Database. This endpoint has many ways to respond back. It could return 200 for success, 400 for unauthorized access, 500 for server errors, or even worse, it might never answer back.<\/p>\n\n\n\n

<\/div>\n\n\n
\n
\"\"<\/figure><\/div>\n\n\n
<\/div>\n\n\n\n

In cases of failure, clients either deal with it with error handling methods that give our artist some information about what went wrong or, in case we don\u2019t want to interrupt the artist\u2019s journey, they schedule it to try again. But beware: We want to be careful in this case to not overload the system with requests. Which is why it is recommended to implement exponential backoff.<\/p>\n\n\n\n

Exponential backoff<\/strong> is a standard error-handling strategy for network applications. In this approach, a client periodically retries a failed request with increasing delays. Clients should use exponential backoff for all requests that return HTTP 5xx and 429 response codes, as well as for disconnections from the server. Eventually, the client should reach either a limit of maximum retries or time and stop attempting to communicate with the server. The great thing about exponential backoff is that it ensures that, when the Server is amidst an incident, it is not flooded with requests.<\/p>\n\n\n\n

But, how do we know if the first request actually failed<\/strong>?<\/p>\n\n\n\n

As we said before, there can be many reasons why an API could not respond back to the client. So, how are we sure that the server\u2019s database hasn\u2019t already saved the song? If one of our retries succeeds, we could end up having submitted the same song twice. This is a big problem, because what we actually wanted to do is to make sure our whole operation is idempotent.<\/strong><\/p>\n\n\n\n

Idempotence means that, if an identical request has been made once or several times in a row, it results in the same effect while leaving the server in the same state.<\/strong><\/p><\/blockquote>\n\n\n\n

A great everyday example of idempotence is a dual button ON\/OFF setup. Pressing ON once or multiple times results in only 1 result: the system is on. Same goes for the OFF button. <\/p>\n\n\n\n

When talking about idempotence in the context of HTTP, another term that pops up is data safety<\/strong>. In that case, safety means that the request doesn\u2019t mutate data on invocation<\/strong>. The table below shows commonly used HTTP methods, their safety and idempotence.<\/p>\n\n\n\n

+——————-+————–+——————-+<\/p>\n\n\n\n

|    Http Method    |    Safety    |    Idempotency    |<\/p>\n\n\n\n

+——————-+————–+——————-+<\/p>\n\n\n\n

| GET               | Yes          | Yes               |<\/p>\n\n\n\n

| PUT               | No           | Yes               |<\/p>\n\n\n\n

| POST              | No           | No                |<\/p>\n\n\n\n

| DELETE            | No           | Yes               |<\/p>\n\n\n\n

| PATCH             | No           | No                |<\/p>\n\n\n\n

+——————-+————–+——————-+<\/p>\n\n\n\n

So as we can see, our POST method fails at both. Great.<\/em><\/p>\n\n\n\n

Solution<\/strong><\/h3>\n\n\n\n

Let\u2019s go back to our whole operation. What do we have?<\/p>\n\n\n\n

We have a client that tells the Server that it needs to save the song. A possible scenario of that JSON request could look like this:<\/p>\n\n\n\n

{<\/p>\n\n\n\n

 userID: \u201cUID-123\u201d,<\/p>\n\n\n\n

 songTitle: \u201cComfortably Numb\u201d,<\/p>\n\n\n\n

 songArtist: \u201cPink Floyd\u201d,<\/p>\n\n\n\n

 songReleaseDate: \u201c1979\u201d<\/p>\n\n\n\n

}<\/p>\n\n\n\n

We could ask the client to perform this request as an idempotent request, by providing an additional Idempotency-Key: <key> header to the request.<\/p>\n\n\n\n

An idempotency key<\/strong> is a unique value generated by the Client, which the server uses to recognize subsequent attempts of the same request. How you create unique keys is up to you, but it\u2019s suggested to use V4 UUIDs, or another random string with enough entropy to avoid collisions.<\/p>\n\n\n\n

When the Server receives this Idempotency-Key, it should save in the database the body of the first request made <\/strong>for any given idempotency key <\/strong>and resulting status code<\/strong>, regardless of whether it succeeded or failed.<\/p>\n\n\n\n

<\/p>\n\n\n\n

<\/div>\n\n\n
\n
\"\"\/<\/figure><\/div>\n\n\n
<\/div>\n\n\n\n

Now, for every request that comes, the Server can verify if it has already<\/strong> mutated the data, <\/strong>just by checking the status in its DB. The idempotency layer should compare incoming parameters to those of the original request and errors (unless they\u2019re the same) to prevent accidental misuse.<\/p>\n\n\n\n

With this solution, we no longer have to worry about duplication of data or conflicts. it ensures that, no matter how many times we repeat this process, our operation is idempotent and the artist will receive the success message when the system is able to save their song.<\/p>\n\n\n\n

These Idempotency-Keys should be eligible for removal automatically after they\u2019re at least 24 hours old.<\/p>\n\n\n\n

P.S. <\/strong>For the simplicity of the example we saved our songs and the keys to the same database. Ideally, you will save these keys on a cache server (e.g. Redis) with a TTL of 24hours, so the removal of the old keys happens by default.<\/p>\n\n\n\n

In conclusion<\/strong><\/h3>\n\n\n\n

An application that uses an API which implements idempotence can follow the steps below to ensure proper usage:<\/p>\n\n\n\n

  1. Create idempotence keys and attach them to the header.<\/li>
  2. When a request is unsuccessful, follow a retry policy such as exponential backoff.<\/li>
  3. Save the request body and idempotency key in a cache server.<\/li>
  4. Mutate the data.<\/li>
  5. Update the idempotency key with the result of the mutation<\/li>
  6. After a failure of either 5xx, 429 or no response from the server, the client retries the request.<\/li>
  7. The server validates if the idempotency key exists on the cache server.<\/li>
  8. The server validates if the body of the request is the same as the one in cache server<\/li>
  9. If everything is the same, the server will not mutate the data but return the previously saved result of the mutation.

    <\/li><\/ol>\n\n\n\n
    \n
    \n
    \"\"<\/figure>\n<\/div>\n\n\n\n
    \n

    Elektra Bilali Simou<\/p>\n\n\n\n

    Engineering manager ORFIUM<\/p>\n\n\n\n

    https:\/\/github.com\/elektracodes<\/a><\/p>\n\n\n\n

    https:\/\/www.linkedin.com\/in\/elektra-bilali-simou\/<\/a><\/p>\n\n\n\n

    <\/a><\/p>\n\n\n\n

    <\/a><\/p>\n<\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"

    Photo by Tim Mossholder on Unsplash There is a question to which typically we, as Developers, kind of turn a b […]<\/p>\n","protected":false},"author":2,"featured_media":1929,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"_seopress_robots_primary_cat":"none","_seopress_titles_title":"","_seopress_titles_desc":"","_seopress_robots_index":"","content-type":"","footnotes":""},"categories":[19],"tags":[],"acf":[],"_links":{"self":[{"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/posts\/1965"}],"collection":[{"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/comments?post=1965"}],"version-history":[{"count":1,"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/posts\/1965\/revisions"}],"predecessor-version":[{"id":1966,"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/posts\/1965\/revisions\/1966"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/media\/1929"}],"wp:attachment":[{"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/media?parent=1965"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/categories?post=1965"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.orfium.com\/ja\/wp-json\/wp\/v2\/tags?post=1965"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}