Synchronous vs Asynchronous API Calls

I have read a bunch of blog posts talking about synchronous and asynchronous API calls, but I found that most of them mix the idea of an API call being synchronous or asynchronous with the idea of the language supporting asynchronous programming.

So here it is, with no discussion of asynchronous programming in any language.

Preamble

Before I get into the difference between synchronous and asynchronous API calls, let me make this clear: with both sync and async calls, you will make a HTTP request, and you will receive a HTTP response as fast as the service and network can handle the HTTP request and send the response.

The difference is what the response means to the client. One will have the business data you wanted, and the other will have some sort of acknowledgement that your request was received and is being worked on, but it won’t have the business data you wanted.

Synchronous API Calls

With a synchronous API call, the response you get has the business data you are looking for or has performed the business action you wanted.

For example, you want to login to a website. You send the username and password to the login endpoint, and you get a response that indicates success or failure of the login attempt, and includes some sort of token.

You use a text messaging service, you send a single message to it, and get back a response that indicates whether the message was sent successfully or not.

The key point is that the response you get from a synchronous API call is the final response; you have the business data you wanted.

Asynchronous API Calls

With an asynchronous API call, you get back some business data that acknowledges you made a request and that it is being worked on, queued, etc. The business data will often include a reference that you can use to check the status of the request.

Take the text messaging service example again. You send a message to the service, and you get back a response that includes a message ID and says delivery is pending. You can then use the message ID to check the status of the message on some other service.

You could also send a request that has hundreds of messages to the service, and you would get back a response with some sort of reference to the group of messages, or possibly a reference for each message. You would then use the reference to look up the status later.

The key point is that the response you get from an asynchronous API call does not have the business data you wanted, but you will have a way to look it up later.

Conclusion

• If the response has the business data you wanted, it’s a synchronous API call.

• If the response is just an acknowledgement that your request was received and is being worked on, it is an asynchronous API call.

That’s it, you don’t have to think about the programming language at all, just what the response from the API call means.