Dealing with Asynchronous Requests on APIs

When developing an API sometimes your services might depend on Providers, i.e. Third Party services, to execute a certain behavior.

One of the questions you might be confronted with is if there are Asynchronous Requests and how you should deal with them.

Here I will be referring to:

Most commonly when contacting an API, the client will receive a final answer to its request. Meaning that in the same connection you will receive an answer.

If for any reason your request fails due to availability problems then you can later retry the same request. Hopefully, at the time of this retry, the Provider’s services will be available.

Sometimes the Provider’s services depend on behaviors that can take more time or effort than the intended, due to dependencies or other factors. To ensure a small response time, the services are divided into two parts:

When you have this behavior, the data has a first moment when it is “created” and only after receiving the “notification” request will it transition to “complete”.

This means that the data needs to persist between the two requests, implying that after the first one the API can’t return a proper result (for the sake of simplicity, we will ignore the possibility of an API Client for our API).

With this Notification, the API will be able to continue its work. Ending by answering the Provider.

BUT, what if the “notification” Service work is complex and can fail? What if it can take long intervals of time to complete its work?

Do we want the Provider to wait while the API is working on the Notification Service? Or can it be released at a specific moment?

One approach to this is to divide the “notification” service into two parts:

With this method, the Prepare will result in an answer for the Provider to understand the success in preparing for the Compute.

BUT, what if it fails?

This logic can fail in two moments the Prepare or Compute. The Prepare part ends when it successfully saves the answer on the “notification”. After this point, the Compute part starts.

However, if for any reason the API couldn’t successfully save the notification then this logic will break and will need to restart.

Hopefully, the Provider retries the “notification” Request. If we have any kind of retry mechanism, it should represent a dependency only to the necessary computation to prepare the “notification” Service.

One approach is to use the HTTP Status as a method to signal if the retry should be done. In this case, if the “notification” Service returns a HTTP Status different from 200 OK then a retry is done.

When the Provider receives a HTTP Status different from 200 OK it schedules a retry for the “notification” request at a later time.

After we have gone through Prepare part without failing then we can start the Compute section. Also here it can fail, but from here on the recovery does not imply depending on a third party and can be more easily managed to depend on the availability of resources.

There is much more that can be discussed here and all of these points represent an approach to Asynchronous Requests.

For instance, we didn't detail what the Prepare technically represents or how to recover from a failure in Compute. These can highly change depending on what you are doing and how you plan to do it.

But before going on I would like to end with what I believe are the main points of this article:

I hope you can take from here some ideas on how to deal with Asynchronous Requests.

Related posts:

The U.S. Justice Department will “announce a major, international cryptocurrency enforcement action” on Wednesday, it said in a statement, adding the U.S. Treasury Department will also make an…