What is an API (Application Programming Interface)?

API (Application Programming Interface) plays the role of a bridge through which different software can communicate and interact with each other.

What is an API (Application Programming Interface)?

Overview

API stands for application programming interface, which is a set of definitions and protocols for building and integrating application software.

How do APIs work?

APIs let your product or service communicate with other products and services without having to know how they’re implemented. This can simplify app development, saving time and money. When you’re designing new tools and products—or managing existing ones—APIs give you flexibility; simplify design, administration, and use; and provide opportunities for innovation.

APIs are sometimes thought of as contracts, with documentation that represents an agreement between parties: If party 1 sends a remote request structured a particular way, this is how party 2’s software will respond.

Because APIs simplify how developers integrate new application components into an existing architecture, they help business and IT teams collaborate. Business needs often change quickly in response to ever shifting digital markets, where new competitors can change a whole industry with a new app. In order to stay competitive, it's important to support the rapid development and deployment of innovative services. Cloud-native application development is an identifiable way to increase development speed, and it relies on connecting a microservices application architecture through APIs.

APIs are a simplified way to connect your own infrastructure through cloud-native app development, but they also allow you to share your data with customers and other external users. Public APIs represent unique business value because they can simplify and expand how you connect with your partners, as well as potentially monetize your data (the Google Maps API is a popular example).

API release policies

  • Private: The API is only for use internally. This gives companies the most control over their API.
  • Partner: The API is shared with specific business partners. This can provide additional revenue streams without compromising quality.
  • Public: The API is available to everyone. This allows third parties to develop apps that interact with your API and can be a source for innovation.

Remote APIs

Remote APIs are designed to interact through a communications network. By remote, we mean that the resources being manipulated by the API are somewhere outside the computer making the request. Because the most widely used communications network is the internet, most APIs are designed based on web standards. Not all remote APIs are web APIs, but it’s fair to assume that web APIs are remote.

Web APIs typically use HTTP for request messages and provide a definition of the structure of response messages. These response messages usually take the form of an XML or JSON file. Both XML and JSON are preferred formats because they present data in a way that’s easy for other apps to manipulate.

SOAP vs. REST

As web APIs have spread, a protocol specification was developed to help standardize information exchange: Simple Object Access Protocol, more casually known as SOAP. APIs designed with SOAP use XML for their message format and receive requests through HTTP or SMTP. SOAP makes it easier for apps running in different environments or written in different languages to share information.

Another specification is Representational State Transfer (REST). Web APIs that adhere to the REST architectural constraints are called RESTful APIs. REST differs from SOAP in a fundamental way: SOAP is a protocol, whereas REST is an architectural style. This means that there’s no official standard for RESTful web APIs. As defined in Roy Fielding’s dissertation “Architectural Styles and the Design of Network-based Software Architectures,” APIs are RESTful as long as they comply with the 6 guiding constraints of a RESTful system:

Client-server architecture: REST architecture is composed of clients, servers, and resources, and it handles requests through HTTP.

Statelessness: No client content is stored on the server between requests. Information about the session state is, instead, held with the client.

Cacheability: Caching can eliminate the need for some client-server interactions.

Layered system: Client-server interactions can be mediated by additional layers. These layers could offer additional features like load balancing, shared caches, or security.

Code on demand (optional): Servers can extend the functionality of a client by transferring executable code.

Uniform interface: This constraint is core to the design of RESTful APIs and includes 4 facets:

  1. Resource identification in requests: Resources are identified in requests and are separate from the representations returned to the client.
  2. Resource manipulation through representations: Clients receive files that represent resources. These representations must have enough information to allow modification or deletion.
  3. Self-descriptive messages: Each message returned to a client contains enough information to describe how the client should process the information.
  4. Hypermedia as the engine of application state: After accessing a resource, the REST client should be able to discover through hyperlinks all other actions that are currently available.

These constraints may seem like a lot but they’re much simpler than a prescribed protocol. For this reason RESTful APIs are becoming more prevalent than SOAP.

In recent years, the OpenAPI specification has emerged as a common standard for defining REST APIs. OpenAPI establishes a language-agnostic way for developers to build REST API interfaces so that users can understand them with minimal guesswork.

Another API standard to emerge is GraphQL, a query language and server-side runtime that’s an alternative to REST. GraphQL prioritizes giving clients exactly the data they request and no more. As an alternative to REST, GraphQL lets developers construct requests that pull data from multiple data sources in a single API call.

SOA vs. microservices architecture

The 2 architectural approaches that use remote APIs most are service-oriented architecture (SOA) and microservices architecture. SOA, the oldest of the 2 approaches, began as an improvement to monolithic apps. Whereas a single monolithic app does everything, some functions can be supplied by different apps that are loosely coupled through an integration pattern, like an enterprise service bus (ESB).

While SOA is, in most respects, simpler than a monolithic architecture, it carries a risk of cascading changes throughout the environment if component interactions are not clearly understood. This additional complexity reintroduces some of the problems SOA sought to remedy.

Microservices architectures are similar to SOA patterns in their use of specialized, loosely coupled services. But they go even further in breaking down traditional architectures. The services within the microservices architecture use a common messaging framework, like RESTful APIs. They use RESTful APIs to communicate with each other without difficult data conversion transactions or additional integration layers. Using RESTful APIs allows, and even encourages, faster delivery of new features and updates. Each service is discrete. One service can be replaced, enhanced, or dropped without affecting any other service in the architecture. This lightweight architecture helps optimize distributed or cloud resources and supports dynamic scalability for individual services.

APIs vs webhooks

A webhook is an HTTP-based callback function that allows lightweight, event-driven communication between 2 APIs. Webhooks are used by a wide variety of web apps to receive small amounts of data from other apps, but webhooks can also be used to trigger automation workflows in GitOps environments.

Webhooks are often referred to as reverse APIs or push APIs, because they put the responsibility of communication on the server, rather than the client. Instead of the client sending HTTP requests—asking for data until the server responds—the server sends the client a single HTTP POST request as soon as the data is available. Despite their nicknames, webhooks are not APIs; they work together. An application must have an API to use a webhook.