One of the most foundational — and important — elements of API design is the choice of paradigm. No matter the business logic or the situational needs to an API, understanding both why a paradigm is chosen and why others were not is paramount to the successful build of any system.

Today, we’re going to look at two approaches in the API space: traditional web APIs and Webhooks. Note that while Webhooks are technically APIs, we will be referring to APIs in the classic sense (as we will soon discuss).

What Is an API?

An API, or Application Programming Interface, is at its most basic form an intermediary between information and those who need to know the information. While this typically takes the form of an intermediary between two applications or systems in a local sense, when we start discussing networked devices, the sky’s the limit — an API can facilitate everything from running microservice-based data manipulation to 3D modeling.

What makes an API different from a Webhook is how a user interacts with it. Typically, when we refer to an API, we are actually referring to a specific type of API within a much larger collection of types. The difference between a Webhook and an API is very much a “square and rectangle” relationship; all Webhooks are APIs, but not all APIs are Webhooks. What separates the common conception of the API from Webhooks is the nature in which data is transferred to the user.

In the common API sense, data is served upon request, such as when a user performs an action, requests a data chunk, or uploads data for processing with a request for the output. APIs are, in this way, extremely reactive — they react to the request, but typically do nothing on their own without prompting from the user.

What is a Webhook?

Webhooks go by many names, including Reverse API or Push API. Simply, Webhooks are APIs that proactively share information rather than reactively. A Webhook is made to monitor information and data systems, tracking changes in state over the service. When a state change is detected, the Webhook will then “push” this information to the person who has requested an update.

In essence, this is a proactive system, responding to events with a reactive push. Contrasted against APIs, webhooks are reactive, responding to the user request and pushing that data only upon request. This may seem like a simple inversion, but it is a fundamental change in the communication paradigm that makes Webhooks a very different technology for very different use cases.

APIs vs. Webhooks

One way to think about APIs and their relationship to Webhooks is to consider a simple analogy. Let’s say that you, the reader, wanted to borrow a book from the library. When you go to this library, there is a set of procedures and processes you must follow to get this book, one of which is the librarian checking the stock of the book. At this point, this checks whether the book is in stock, where it is on the shelf, or if it’s not in stock, when it will be returned.

In an API frame of mind, the stock information is something that must be created. You must walk up to the library, ask the information of the librarian, and wait for all of that information to be gathered, collated, compared, and eventually served to you. An API in the general sense functions just like this — the user must request a chunk of data and wait for it to be served.

The drawback here, of course, is that you must constantly go to the library to check on this stock, which wastes resources (and can be very frustrating). Wouldn’t it be better to only get this updated data when the data itself is actually updated? Wouldn’t it simply be better if the librarian were to track the stock of the book, reference the name that was left in a ledger, and update that person when the state of the book in the library changed?

This is the basic concept of Webhooks. In this relationship, you can tell the system that you would like to monitor the state change, and when a change does occur, to be notified and linked to it. This is better in certain situations, but it does come with its own pros and cons, most notably the fact that the information flow only occurs in a single direction. Without more work, you can’t really respond to a pure Webhook with additional requests for processing.

When to Use APIs and Webhooks

Choosing whether or not to utilize a classical “pull” API or a “push” Webhook comes down to how the data is intended to flow. APIs have a fundamental data flow from the user to the source. The user will request information in some form, the API will deliver the data in some form, and the request will be fulfilled in a particular order. It is that order that determines the appropriateness of each of these technologies.

When data is meant to flow from a state change in the source to the user, a Webhook is most appropriate. This process will generally take the form of a source generating information or data that causes a state change, which triggers a defined process to collect, collate, and serve this data. Whether the user must first subscribe or simply be connected to the endpoint is a secondary question, as the important facet of this process is that the flow must be from the source and to the user.

On the other hand, APIs are much more appropriate when the data should flow from the user to the source. This might seem confusing — after all, the user wants the data, not the other way around — but consider for a second what data the user is providing. In a classical API structure, the initial data sent is the structured request from the user detailing what is being requested, from where, and in what form. This serves as the first data source in a chain of data that ultimately results in the user pulling from the system. In this way, the user requests, and is then updated.

Let’s look at two simple examples of where each technology shines. Let’s say we have a service that collates audiobooks and provides them to a subscribed use. The underlying system is essentially a database that ties together audio streams and user accounts, acting as a gatekeeper of sorts. In this scenario, our business model will wholly determine which technology we adopt.

If our model is that, once a month, a user is automatically served a specific audiobook dependent on tastes, subscription types, genres, or other types of content categories, we would use a Webhook. In this case, a Webhook can leverage existing user data to determine what audiobook the user will want. Upon detecting a state change (in this case, the start of a “new month”), this content is served automatically to the user as a push of data.

Let’s say we wanted the user to have greater control over this service. In another model, we may want our users to be able to use digital tokens to choose a book from a list of books. A standard API is most appropriate in such a model, as we need the user to make a specific request using specified resources to get a book. This data relationship is pull, not push, and as such, a Webhook would not be appropriate.

Of note is the fact that both of these technologies, in theory, could exist at the same time. Perhaps our two business models could be different tiered experiences. For instance, we could use the Webhook model for a “low-cost tier,” where the user does not have an unlimited choice but still gets a curated book every month, while still using a secondary API model for a “premium tier,” which the user can utilize after receiving their monthly book to “exchange” for a book they wanted. In this design paradigm, we essentially have two distinct processes and business models that support one another and serve both sides of the “push-pull” coin.

Conclusion

“Classic” APIs and Webhooks both represent common situations in the web development sphere — no one solution is better. Instead, both solutions have their time and place, and in some instances, there may even be times and places where both are appropriate within the very same system. Leveraging the suitable model will enable higher user experience and functionality, as well as greater control over the flow of information to support the business logic. Ultimately, the most appropriate model will be dependent on various factors, including the business model, the user demand, and the foundational needs of the consumer.

What do you think about these two paradigms? Is there a newer model of API consumption you would like to see covered in the future on Nordic APIs? Let us know in the comments below!