You might have heard of an Application Programming Interface (API), but did you know there are multiple kinds of them? As it turns out, not every API is a REST API that returns results immediately. (This, by the way, is the most common type of API in the world of web services.)
You’ve likely run into many kinds of APIs without even knowing it. After all, they are a way to talk to applications, so they almost always operate behind the scenes. Even clicking on a Facebook profile sends API calls that return nearly all of the information displayed on the following page.
So, what are the other kinds of APIs? There are a few different architectures and protocols. In this article, we’ll focus on asynchronous APIs and how they compare to synchronous APIs.
Table of Contents
What is an asynchronous API?
An asynchronous API, or async API for short, is essentially an API that does not provide data immediately. It's implied that the user will likely have to wait until later for the data from their request to be delivered.
This can be a few minutes, hours, or longer. That depends on the service or application in question.
There are many situations where this makes sense, like when there is so much demand for a service that it can’t possibly get all of the data out instantly to users. Sometimes, it simply doesn’t make sense for the service to be instant because the purpose or function of the communication isn’t instant itself.
For example, sending and receiving emails is a service that wouldn’t necessarily be instantaneous. Sure, someone could reply pretty much immediately using email. However, the expectation is that it will take some time to receive a reply.
Asynchronous vs. Synchronous APIs
As you might’ve guessed, if an asynchronous API is an API that returns data at a later date, then a synchronous API is expected to return data very quickly, if not instantly.
Synchronous APIs also usually use HTTP or HTTPS for transport, which are the protocols we use to navigate the web. You type in a website URL. Then, it sends off an HTTP or HTTPS request to a server. After, you get an HTTP or HTTPS response back.
This is a synchronous API in action!
Another difference, synchronous APIs tend to be unidirectional, while async APIs tend to be bidirectional. This means that while synchronous APIs give you data from a server, you won't be both pushing data to and downloading data from the server simultaneously.
Asynchronous APIs, on the other hand, are bidirectional. This means data can go both directions at once.
Think of an instant messaging system where you can send and receive messages simultaneously. You're not guaranteed an immediate response (though you will usually get a notification when the data is ready).
Some APIs don’t fit neatly into these boxes. Perhaps an API might use HTTP but also support a form of instant messaging. A couple of examples are the XMLHttpRequest Web API and the GraphQL API. Both of these support a form of synchronous and asynchronous communication.
When to Use Asynchronous APIs
Speaking of use cases, let’s discuss a few possible reasons you might consider using an async API.
The first and most obvious example is if you’re using email or some other form of delayed communication, such as instant messaging. Multiple different asynchronous messaging protocols can be used for APIs, such as Webhooks, WebSockets, GraphQL subscriptions, and Server-sent events (SSE).
Asynchronous APIs can also manage transactions in the world of banking. Credit transactions can be handled with an async API to provide a single method of facilitating payments between multiple merchants and a bank.
Since it’s often possible to schedule payments, using async APIs makes sense here. The world wouldn’t work the same if everything had to be instant, especially in banking.
There is also the use of async APIs in multiplayer games. Often, multiplayer games will gather input from multiple players and return a response to all the players after processing input from everyone, usually happening at a set interval or “tick.”
This means that the users constantly send and receive data from the server simultaneously. Though this may appear to be happening instantaneously, the data exchange is not actually happening in real time due to varying amounts of latency among the players.
Examples of Asynchronous APIs
One extremely popular example of an async API in action is Facebook Messenger. It’s an instant messaging client available both in a browser and as a standalone app on mobile devices.
It primarily uses the Send API to send messages to users, including text, attachments, and more. To send a message, a POST request will be used at one of the API endpoints.
Various parameters are also used to specify details about the message, such as what kind of message it is, whether it has an attachment or not, or even if someone is currently typing or has read the message.
Multiplayer Video Games
Multiplayer video games are another massively popular use for asynchronous APIs in the real world. Chances are that you’ve heard of the above example, World of Warcraft, or WoW for short.
As mentioned earlier, multiplayer video games often use asynchronous APIs to allow communication with and between the players.
While WoW uses multiple API types to accomplish all of its functionality, the Event API is an example of an async API used for passing messages. This includes the in-game mail system and the chat used to communicate with other players.
The endpoint also works with POST requests, much like the previous example.
Gmail is another wildly popular example of asynchronous APIs in action. While some parts of the Gmail API may function similarly to a synchronous API, the API is largely an asynchronous API since there is no expectation of an immediate response when dealing with emails.
Messages can be created, modified, and sent off via the appropriate API endpoint using a POST or PUT request, alongside any important HTTP headers to specify things like the number of bytes being sent and the type of content you are uploading.
The JSON response will return things like the headers of the request, the Multipurpose Internet Mail Extensions (MIME) type, estimated file size, etc. This information can then be used in other applications or requests.
If you had to choose only one example on the list to learn from, this might be the best choice. It has some of the best documentation available and is so ubiquitous even the most casual user could likely think of a way to use it in everyday life.
Many other Google products have asynchronous aspects as well, such as Google Sheets and Google Docs.
Asana is primarily a way to communicate asynchronously about work. It's a project or task management tool with many features, such as due dates, forms, comments, calendars, searching, reporting, and team management.
It‘s yet another RESTful API using HTTP features. However, it’s not entirely synchronous. Some asynchronous features include using webhooks, managing custom fields, sending/receiving attachments, and managing tasks.
Like the other APIs in this list, HTTP methods are generally used to create, read, update, or delete things through the API, with various headers available for further specificity.
Asynchronous vs. Synchronous APIs — Making the Best Choice for Your Project
It‘s important to consider a few things when choosing a synchronous or asynchronous API for your project. It will largely depend on the project and use case, but let’s review a few crucial features and differences to consider when deciding.
Asynchronous APIs imply a delayed response. Other functions can continue to run while the asynchronous function awaits a response in the background. This is ideal for messaging systems, but not so great if you're just reading data in a database.
Asynchronous APIs are also bidirectional, as opposed to unidirectional. Again, this is ideal for when there is going to be a lot of communication back and forth between the server and client(s), but probably not necessary if communication is one way.
It's also smart to consider if every request needs a response or if multiple requests can be processed in parallel. Asynchronous APIs are great for the latter, while synchronous APIs might be a better bet for the former.
Finally, perhaps decide how complicated you‘re willing to let the API get. Asynchronous APIs are more complicated for everyone involved, but that doesn’t necessarily disqualify them from being the best choice in many scenarios.
In conclusion, there are many different uses for both synchronous and asynchronous APIs. The main differences are that synchronous APIs generally respond nearly instantaneously and are unidirectional, while asynchronous APIs respond later and are bidirectional. Asynchronous APIs can also process large amounts of requests in parallel to return at a later date.
Many popular web services use asynchronous APIs to function, most of which are some form of messaging service, though other asynchronous services exist. Don't be afraid to play around with their APIs to help learn how this all works in action.