Speaker 1: Welcome to the new video in the REST API series and today we will talk about asynchronous APIs. Have you ever wondered what happens when you send a particular request to an API to fetch the data? You get the response right away. Okay. Now, what happens when you try to upload a file? Then also you get the response pretty quickly. But what happens when you try to upload quite a big file? You get a progress bar, okay? And that progress bar shows you that how much of the file upload is complete and how much more time it will take. Do you think that for these APIs the response is instant or what do we call those APIs for which you get an instant response versus the APIs for which you don't get an instant response but instead you get to see a progress bar? We are going to discuss synchronous and asynchronous APIs in this video and find answers to all those questions. So let's get started. Whatever REST APIs we have discussed till now used to return the response to us very quickly within a matter of milliseconds. All those APIs can also be understood as synchronous APIs. What could be the real-world example of a synchronous API that you go to a grocery store, you pick up something, an item that you want to buy, you exchange money, you get the item and then you come back home, right? Whatever you wanted to purchase, you didn't have to wait much for it, you just got it back within a matter of few minutes and your work is done, right? So this transaction was synchronous, that you asked for an item, you got an item, you paid the money and this is done. I have included such example in one of the previous videos as well where I have talked about buying something from a local grocery shop. Now think about a big restaurant where you have went to dine-in and it's a self-service restaurant. What happens there? You place your request and you get a token and that token has some particular number and there is somewhere a board which is displaying when your food is ready and as soon as that board displays your token number, you go and collect your food. Now this is called asynchronous operation. Why? Because when you place the order and paid the money, you didn't get the food in response. Instead, you got a token and now you have to wait for that token and wait in line or just wait somewhere for your food to be ready so that you can collect your food. Why? Because when you go to buy items from grocery shop or a local grocery shop, those items are already ready to take away. So you can just quickly grab them, pay the money and go home. But in case of food or in case of a restaurant where you are waiting for food, preparation of your food takes some time and they cannot give you the food instantly because it is not ready. We have to go back in the kitchen and prepare it for you. So it is a long-running process. It is a long-running process. It takes some time and that is why you have to wait. But also you would like to know that when your food is ready and hence the whole token system comes into the picture. We have to do similar things when it comes to APIs and long-running operations. Now what could be the example of long-running operations? I have just given one example. Whenever you have to upload a very big file, it is a long-running operation. It cannot get completed within a matter of milliseconds or seconds. And especially if the file is huge, let's say the file is 1 GB or 2 GB or even larger than that, it is not going to get completed within a few seconds. And if the API provider is going to keep you waiting for it, it will take a very long time and it will cause unnecessary latency in your API response. You don't want that. The person who has built the product don't want a bad user experience. And hence there are asynchronous APIs. Now let's talk about how asynchronous APIs are implemented. So let's say you are giving an API for a long-running operation. Now you design a put or post API for it. You design an endpoint and you take the data, either it's a large file or some other data that is available in payload, which is going to trigger a long-running operation. As soon as you take this request, in the response of this API, you are not going to give 200 as a response. You are going to give 202 as a response, which means that we have accepted your request. Very similar to the restaurant where they have accepted your request and in return you have to give them a token. Now what would that token be? The token would be the location of where this operation is happening or the status of that operation. So the HTTP code will be 202 and in the location header, which we have discussed in the headers video, the location header will be an endpoint, let's say API slash some number slash status. Now what will you do with this endpoint that has been returned to you in the location header along with the 202 response code? You can use this particular API endpoint in order to fetch the status of your upload file operation or your long-running operation. As soon as you hit get request with this new API, which has your request status and your token, your request ID, in response you can get something like that the operation is in progress or the status is in progress or it is completed or it is failed. If it is failed, there might be a reason like why this is failed, maybe you uploaded something wrong. If it is completed, then you are good to go. If it is in progress, it might also give you a link to cancel the operation or it might give additional information like this is the ETA and in this much time it is going to get completed. So, this is the way the asynchronous APIs are handled, right? You send a request, you get a request ID, using that request ID and that endpoint which has been given to you in order to find the status of a long-running operation, you hit that API using get and that endpoint and you get the status of your long-running operation. So, this is how the whole process works and please note the HTTP written code here in case of your first long-running operation API is 202 and not 200. Now, what happens when this operation has been completed? When you hit the API, the status API with the request ID and the operation has been completed, in some cases the implementation is done in a way where the status code, the HTTP status code is 303 and in the location header will be the endpoint where your newly created resource exists. Okay? So, it might be something like API something and your ID of your resource. Now, this ID is not your request ID. This ID is the resource ID of the file or data that you might have uploaded. That means that the operation is completed and this is the location where you can find your newly created resource. Now, this was one way of implementing asynchronous APIs. What is the another way? The another way is not so different from the first one. It's just the difference of how you want to tailor the response. So, in the first way, you have tailored the response using different HTTP codes like 202 and 303 and sending the data in the location headers. In another way, what you can do is you can use your basic HTTP codes like 200 and you can send that data in form of response body as well. How? So, let's say that the client is hitting your API for a long running operation. In the response, you can say 200 and in the body, you can give them the token ID or the request ID and also the API endpoint or the link where they can hit in order to get the status of the request. The same information that you have shared in the location header, you can share in the response body as well. And once this gets completed and when the user tries to hit the status API, in that response also, instead of giving 303 or instead of giving separate responses, you can directly give 200 with the status. The status could be completed or in progress or failed. And along with different status, the data can, the data in the response body can be changed. For example, if the status is in progress, you can send ETA. If the status is completed, you can send the location of the newly created resource. If the status is failed, you can send the reason why it has failed and so on. So, basically you can implement it both ways. The practice or the standard practice is to do it in the first way using 202 and 303 codes because it seems more organized, but you can take the second approach as well. It depends on your implementation and the decisions that your team takes. Now let's talk about what are the use cases of asynchronous APIs. As I have also discussed earlier, when you are not able to give the response or whatever the client or anyone who is hitting your API has requested in a very small amount of time or in a very small latency, which are long running operations or which you know can take time. In those cases, you turn to asynchronous APIs. This whole pattern is also known as asynchronous request-response pattern. If I have left out any piece of information or if you think that something is missing from this or if some part was confusing, please feel free to comment below and I will try to address it either in comments or through a new video. Till then, take care. See you in the next video.