TL;DR: An API (Application Programming Interface) enables two-way communication between software applications driven by requests. A webhook is a lightweight API that powers one-way data sharing triggered by events. Together, they enable applications to share data and functionality, and turn the web into something greater than the sum of its parts.
APIs and webhooks both allow different software systems to sync up and share information. As software applications become increasingly interconnected, it is essential for developers to understand the difference between these two means of sharing data, and select the tool that best meets the needs of the task at hand.
Let's dive in.
Let's dive in.
What is an API?
An API is like a portal through which information and functionality can be
shared between two software services. The word “interface” is key to
understanding an API’s purpose. Just like a web browser is an interface
for a human end user to receive, send, and update information on a web
server, an API is an interface that provides software programs with the
same functionality.
shared between two software services. The word “interface” is key to
understanding an API’s purpose. Just like a web browser is an interface
for a human end user to receive, send, and update information on a web
server, an API is an interface that provides software programs with the
same functionality.
There are different types and categories of APIs (which we will explore later), but defined broadly, APIs are the most common way for different software systems to connect and share information. Currently, ProgrammableWeb provides a database of over 23,000 APIs that deal with everything from global epidemiological data to dad jokes. Each API is a blank canvas waiting for developers to tie it into other applications and use it in new, creative ways.
What is a webhook?
A webhook can be thought of as a type of API that is driven by events
rather than requests. Instead of one application making a request to
another to receive a response, a webhook is a service that allows one
program to send data to another as soon as a particular event takes
place.
rather than requests. Instead of one application making a request to
another to receive a response, a webhook is a service that allows one
program to send data to another as soon as a particular event takes
place.
Webhooks are sometimes referred to as “reverse APIs,” because
communication is initiated by the application sending the data rather
than the one receiving it. With web services becoming increasingly
interconnected, webhooks are seeing more action as a lightweight
solution for enabling real-time notifications and data updates without
the need to develop a full-scale API.
communication is initiated by the application sending the data rather
than the one receiving it. With web services becoming increasingly
interconnected, webhooks are seeing more action as a lightweight
solution for enabling real-time notifications and data updates without
the need to develop a full-scale API.
Say for instance you want to receive Slack notifications when tweets
that mention a certain account and contain a specific hashtag are
published.
that mention a certain account and contain a specific hashtag are
published.
Instead of Slack continuously asking Twitter for new posts
meeting these criteria, it makes much more sense for Twitter to send a
notification to Slack only when this event takes place. This is the
purpose of a webhook––instead of having to repeatedly request the data,
the receiving application can sit back and get what it needs without
having to send repeated requests to another system.
meeting these criteria, it makes much more sense for Twitter to send a
notification to Slack only when this event takes place. This is the
purpose of a webhook––instead of having to repeatedly request the data,
the receiving application can sit back and get what it needs without
having to send repeated requests to another system.
APIs enable robust integrations
An important feature of APIs is that they provide two-way communication
between different software programs via a request-response cycle, most
commonly using the HTTP protocol.
between different software programs via a request-response cycle, most
commonly using the HTTP protocol.
In a typical API use case, one software program will ask for a specific
set of data from another using an HTTP GET request. Provided the
request is valid, the receiving system will respond with the requested
data in a machine-readable format, commonly XML or JSON. This is what
allows applications to share data regardless of their individual
programming languages or internal specifications.
set of data from another using an HTTP GET request. Provided the
request is valid, the receiving system will respond with the requested
data in a machine-readable format, commonly XML or JSON. This is what
allows applications to share data regardless of their individual
programming languages or internal specifications.
The universal nature of API interactions can enable countless scenarios, from an iPhone user checking the local temperature via the AccuWeather API to an Uber driver navigating to their next pickup location via the Google Maps API.
In addition to receiving data, APIs can also handle the full gamut of
“CRUD” (Create, Read, Update and Delete) operations between two
applications. In other words, APIs aren’t just for displaying data to a
user in an interface––they can also be used to make changes to it in the
application where it is stored. This is how APIs allow software systems
to expand their services and functionality, and integrate with other
platforms in a more thorough and meaningful way.
“CRUD” (Create, Read, Update and Delete) operations between two
applications. In other words, APIs aren’t just for displaying data to a
user in an interface––they can also be used to make changes to it in the
application where it is stored. This is how APIs allow software systems
to expand their services and functionality, and integrate with other
platforms in a more thorough and meaningful way.
The versatility of APIs makes them powerful tools for developers to
extend the capabilities of their applications. Most modern web services
include APIs that allow their data and functionality to be incorporated
into other tools––in fact, it would be rare to encounter an enterprise
web service that does not leverage an API from at least one other
application to some extent.
extend the capabilities of their applications. Most modern web services
include APIs that allow their data and functionality to be incorporated
into other tools––in fact, it would be rare to encounter an enterprise
web service that does not leverage an API from at least one other
application to some extent.
Webhooks offer lightweight data sharing
One might think that since webhooks are real-time events that they are
technically difficult to implement. Actually, a key advantage of
webhooks is that they are easier to set up and less resource-intensive
than APIs. Creating an API is a complex process that in some cases can
be as challenging as designing and building an application itself, but
implementing a webhook simply requires setting up a single POST request
on the sending end, establishing a URL on the receiving end to accept
the data, then performing some action on the data once it is received.
technically difficult to implement. Actually, a key advantage of
webhooks is that they are easier to set up and less resource-intensive
than APIs. Creating an API is a complex process that in some cases can
be as challenging as designing and building an application itself, but
implementing a webhook simply requires setting up a single POST request
on the sending end, establishing a URL on the receiving end to accept
the data, then performing some action on the data once it is received.
Common use cases for webhooks include sending new email list
additions and removals to a CRM system, automatically
updating accounting software when invoices are paid, or setting up any
type of notifications. In each of these types of events, the information
flows in one direction, and no request is necessary to receive updated
data.
additions and removals to a CRM system, automatically
updating accounting software when invoices are paid, or setting up any
type of notifications. In each of these types of events, the information
flows in one direction, and no request is necessary to receive updated
data.
The same characteristics that make webhooks relatively easy to implement
are also the reasons why they are far more limited than APIs. Updating
the data a webhook delivers requires re-configuring it entirely to listen
for a different event, and in most cases it would be more efficient to
create a new webhook.
are also the reasons why they are far more limited than APIs. Updating
the data a webhook delivers requires re-configuring it entirely to listen
for a different event, and in most cases it would be more efficient to
create a new webhook.
When two systems share data via an API with multiple endpoints, the receiving system has access to a much broader range of data from the sending system. Also, unlike APIs, webhooks do not allow the sending system to add, update and delete data on the receiving end, which is why webhooks alone are too limited to offer full integration between two applications.
API architecture: Present and future
APIs fall under different categories depending on the protocols and
architectures that define how they send and receive data. Historically,
the most common architectural pattern for API design has been REST,
especially for those servicing web-based applications.
architectures that define how they send and receive data. Historically,
the most common architectural pattern for API design has been REST,
especially for those servicing web-based applications.
REST stands for “Representational State Transfer.” This pattern, defined by Roy Fielding in 2000, allows for two applications to communicate over HTTP in a way similar to browsers and servers. REST is not an official
standard––rather, it is a set of suggestions about how to design APIs
and other web services. An API is considered “RESTful” if its design
abides by the following recommendations:
standard––rather, it is a set of suggestions about how to design APIs
and other web services. An API is considered “RESTful” if its design
abides by the following recommendations:
- Client-Server: Just like a browser requesting a
webpage from a server, in a RESTful API, application A makes a request
to a URL hosted on application B over HTTP. Application B then evaluates
the request and returns either the requested data or an error message. - Stateless: The responding system does not need to know anything about the application state of the system making the request to provide an
appropriate response. The request alone should contain all the
information necessary to deliver the response. - Cacheability: The response should state whether the receiving system is allowed to cache it or not.
- Layered systems: The API does not rely on a particular system to make the request in order to deliver the response. This means the requesting system could either be a client, a proxy, or any other intermediary.
This simple example follows REST conventions. When you visit the URL, your browser will display a suggested activity to take part in if you are bored in JSON format:
{
"activity": "Go to a concert with some friends",
"type": "social",
"participants": 4,
"price": 0.6,
"link": "",
"key": "4558850",
"accessibility": 0.4
}No matter how you make a request to this URL––whether with your browser, with CURL, or an HTTP client library like fetch in JavaScript––the API will return the same object. In addition to REST, other API conventions include SOAP, COBRA and XML-RPC. To date, however, REST the most widely used set of API architecture guidelines.
GraphQL: The Goldilocks of data retrieval
In 2015, the engineering team at Facebook released GraphQL––a
new query language for APIs intended to provide a more flexible
alternative to sending requests to endpoints on REST APIs. Without
getting too deep into the complexities of GraphQL, the main advantage it
offers over traditional REST APIs is its ability to return the exact
data needed with each request while avoiding “over fetching” and “under
fetching,” problems typically encountered with traditional APIs.
new query language for APIs intended to provide a more flexible
alternative to sending requests to endpoints on REST APIs. Without
getting too deep into the complexities of GraphQL, the main advantage it
offers over traditional REST APIs is its ability to return the exact
data needed with each request while avoiding “over fetching” and “under
fetching,” problems typically encountered with traditional APIs.
For example, consider the following situation. A restaurant review app
needs to display the titles of the most recent reviews a user has
published, along with the last three people to follow that user. Using a REST API, the client would typically have to make three different
requests to different endpoints––one to fetch the initial user data, a
second to return all the reviews for that user, and a third to return a
list of that user’s followers. Using GraphQL, a client could access the
same data with a single query the exact requirements:
needs to display the titles of the most recent reviews a user has
published, along with the last three people to follow that user. Using a REST API, the client would typically have to make three different
requests to different endpoints––one to fetch the initial user data, a
second to return all the reviews for that user, and a third to return a
list of that user’s followers. Using GraphQL, a client could access the
same data with a single query the exact requirements:
query {
User(id: "qr3fsdcv24") {
name
posts {
title
}
followers(last: 3) {
name
}
}
}Like Goldilocks, GraphQL seeks to retrieve the amount of data that is "just right."
Hopefully this post has expanded your understanding of these two common methods of sharing data between applications. The same wisdom that applies to all architectures, frameworks, design patters and
technologies in software engineering also holds true for APIs and
webhooks: everything has its time and place. The key to getting the most
out of both tools is knowing which one is right for the job.
technologies in software engineering also holds true for APIs and
webhooks: everything has its time and place. The key to getting the most
out of both tools is knowing which one is right for the job.
Also published on: https://www.mparticle.com/blog/apis-vs-webhooks