What Developers Mean When They Talk About API

API has become one of those catch-all terms that developers throw around without really considering the context. On any given week, you will come across discussions like "How to use the Twitter API", "New framework X is great because it has a low API surface", and "Best practices for building an API."

Is an API a data source? Is it a service? Is it a way to call native functionality? The truth is, in modern software development it can mean any of these things. Before we get into the various use cases that have led to this confusion, let's look at the specific meaning.

An API is an interface

API stands for Application Programming Interface. It is a way to programmatically interact with an application. The programming interface part is more straightforward. It is a set of hooks that allow users—consumers of the API—to use the underlying functionality of the application in some way. Interfaces are a way to interact with an object or device, and programming interfaces are a way for your application to interact with another.

How this works is dependent on the application and language used. This is where documentation is important. It is a guide into how to use an API, what actions are supported, and how to get started.

The Application part of API is where the confusion happens. Let's start by looking at the most common "application", web services.

SaaS, web APIs, and services

When most developers say API they mean services in the form of REST, or in recent years, GraphQL. These service APIs, sometimes called web APIs, allow applications to interact with the features and data of another application. This can include anything from retrieving a user's followers with the Twitter API to training a machine learning model with Microsoft's cognitive vision API.

These APIs often include some form of authentication such as OAuth or an "API key" that enables calls to the API to be made.

This type of API can either be used internally within a company or exposed to the outside world. In many cases, organizations will provide external APIs for some of their internal services as a means to further monetize the features of their products. Google Maps is a great example of this. The Google Maps API is used internally at Google within many of their other products, like search, but is also available to third parties for a fee.

The underlying "platform"

Another definition of the application is the underlying platform or operating system. When you think about client-side javascript, features like DOM manipulation, Fetch requests, and mouse position are all types of APIs. In this case, the browser is the application. In fact, one of the largest hurdles when switching between Node.js development and client-side browser development isn't learning new javascript, but learning the platform-specific APIs.

Similarly, developers working on mobile platforms like iOS interact with APIs that expose portions of the operating system. This could be hardware features like the camera or motion sensor, or interaction features like "taps" or "swipes." In this case, the operating system is the application.

Frameworks and libraries

One more area that you'll often hear the term API used is in relation to frameworks and libraries. These are abstractions built on top of a language or platform that either add features or simplify use cases. For example, in Ruby and Node.js, many HTTP libraries exist to simplify or add functionality to the built-in features of making an HTTP request.

In this case, the application is the framework. When we talk about parts of a library or framework, we often refer to it as the library's API. For example: "Axios uses a simplified API for making requests" or "React's context API allows you to pass data through the component tree." When developers refer to the API surface of a framework or library, they are referring to the number of APIs or parts of the API that exist within the framework.

Learning a new API

Learning an API is the first step in understanding what types of benefits it can offer your application. Some communities offer a consistent experience. For example, Ruby has RubyDoc.info. While it may seem unapproachable at first, it standardizes the documentation across most core and third-party features of the language.

The browser manufacturers have joined forces to support MDN as the recommended place to learn the APIs available in modern browsers.

At Bearer, when we talk about APIs we normally mean web APIs. The kind that your application integrates with and relies upon to add features or functionality. When learning modern web APIs, you'll start to see some trends and pick up a few Best Practices for Navigating an API documentation.

Previously published at https://blog.bearer.sh/what-is-an-api/