What is an API? Application programming interfaces explained

API stands for application programming interface, a concept that applies everywhere from command-line tools to enterprise Java code to Ruby on Rails web apps. An API is a way to pro-grammatically interact with a separate software component or resource.

Unless you write every single line of code from scratch, you’re going to be interacting with external software components, each with its own API. Even if you do write something entirely from scratch, a well-designed software application will have internal APIs to help organize code and make components more reusable. And there are numerous public APIs that allow you to tap into functionality developed elsewhere over the web.

What is an API?

An API is defined as a specification of possible interactions with a software component. What does that mean, exactly? Well, imagine that a car was a software component. Its API would include information about what it can do accelerate, brake, turn on the radio, etc. It would also include information about how you could make it do those things. For instance, to accelerate, you put your foot on the gas pedal and push.

The API doesn’t have to explain what happens inside the engine when you put your foot on the accelerator. That’s why, if you learned to drive a car with an internal combustion engine, you can get behind the wheel of an electric car without having to learn a whole new set of skills. The what and how information come together in the API definition, which is abstract and separate from the car itself.

One thing to keep in mind is that the name of some APIs is often used to refer to both the specification of the interactions and to the actual software component you interact with. The phrase “Twitter API,” for example, not only refers to the set of rules for programmatically interacting with Twitter, but is generally understood to mean the thing you interact with, as in “We’re doing analysis on the tweets we got from the Twitter API.”

API as abstraction layer

When it comes to software, APIs are literally everywhere. APIs go hand in hand with one of the most fundamental concepts in computer science: abstraction. Abstraction is just a way of organizing the complexity of a system so that complicated actions can be handled in a simple way. Think of this abstraction like those Amazon Dash Buttons, the battery operated, push-button circuit boards you can use to order staples from Amazon. This is what they look like:

You order a Dash Button from Amazon and use an app on your smartphone to associate it with your Wi-Fi network, your Amazon account, and a product, say, your favorite brand of paper towels. Then, whenever you want to order more paper towels, you just press the button. The Dash Button connects to the Internet and sends a message to place an order on your account. A few days later, paper towels arrive at your doorstep.

Like an API, the Dash Button is a blissfully simple interface that hides all kinds of complexity behind the scenes. The ID of the product you ordered must be retrieved from some database. Your delivery address must be pulled from your account. The nearest fulfillment center stocking your paper towels must be determined, then notified to remove an item from the available stock and package it up. Finally, the package must be routed through some combination of airplanes, trucks, and vans along with other packages in a way that ensures that all the packages will reach their destinations efficiently.

Now imagine you had to coordinate all of these things as a customer. You’d never order paper towels because it’s too complicated and time consuming and you have better things to do. Luckily, the whole ordeal is abstracted away from you. There is a long, interconnected chain of computer systems and human processes that make those paper towels show up at your doorstep, but all you have to think about is pressing a button.

This is what APIs are like for programmers. They take an overwhelming amount of complexity and define a relatively simple set of interactions that you can utilize instead of doing it all yourself. In any software project, you’re likely using tens if not hundreds of APIs directly, and each of those APIs relies on other APIs and so on.

Public APIs and API integration

APIs are a longstanding concept in computer programming, and they have been part of developers’ toolsets for years. Traditionally, APIs were used to connect code components running on the same machine. With the rise of ubiquitous networking, more and more public APIs, sometimes called open APIs, have become available. Public APIs are outward facing and accessible over the Internet, allowing you to write code that interacts with other vendors’ code online; this process is known as API integration.

These kinds of code mashups allow users to mix and match functionality from different vendors on their own systems. For instance, if you use the marketing automation software Marketo, you can sync your data there with Salesforce CRM functionality.

“Open” or “public” should not be interpreted as meaning “free of charge” in this context. You still need to be a Marketo and Salesforce customer for this to work. But the availability of these APIs makes integration a much simpler process than it otherwise would be.

Web services and APIs

You might recall the term web services from the early ’00s and think that the idea of an open API sounds pretty similar. In fact, a web service is a specific kind of open API, one that meets a fairly rigid set of specifications, including that they be specified in Web Services Description Language (WSDL), an XML variant.

Web services were meant to be used as part of a service-oriented architecture (SOA). As the Nordic APIs blog explains, that gave web services something of a bad name, as SOAs never quite lived up to their potential. Advances in the techniques used for service-to-service communications notably lighter, more flexible REST have also left web services somewhat behind in the world of public APIs.

REST APIs

Web services were originally designed to communicate using SOAP (Simple Object Access Protocol), a messaging protocol that sends XML documents over HTTP. Today, however, most web-based APIs use REST Representational State Transfer as an architectural style.

REST was formally introduced by Roy Fielding in his doctoral dissertation in 2000. It’s a set of architectural components, design principles, and interactions used for building distributed systems that involve media of any kind (text, video, etc.). At its core, REST is a style of building systems that allows for flexible communication and display of information across the web while providing structure necessary to easily build general purpose components.

In a REST API, a resource could be pretty much anything, but examples include a user, a list of tweets, and the current results of a search for tweets. Each of these resources is addressable at a resource identifier, which in the case of web-based REST APIs is usually a URL, such as https://api.twitter.com/1.1/users/show?screen_name=twitterdev. When an application requests a resource using the identifier, the API delivers the current representation of that resource to the application in a format that the application can consume, such as a JPEG image, HTML page, or JSON.

One of the big differentiators of REST is that it involves sending data to the requesting application. While this provides great flexibility, allowing the application to do whatever it wants with the data, it comes at the cost of efficiency. Sending data over the web for processing is quite slow compared to doing the processing where the data resides and then sending the results.

Of course, the problem with the “efficient” approach is that systems hosting the data would need to know what applications want to do with it ahead of time. Thus, in order to build an API that has general purpose usability and flexibility, REST is the way to go.

API examples

There are plenty of public APIs out there for you to interact with, many from industry behemoths. The ability to access some platform company’s code programmatically via an API is what makes them a platform, in essence. Some prominent API examples include:

• Google APIs, which allow you to connect your code to the whole range of Google services, from Maps to Translate. APIs are so important to Google that they acquired Apigee, a leading API management platform.
• Facebook APIs, which allow you to programmatically access Facebook’s social graph and marketing tools. (The company has been restricting just what user data you can access via these APIs in the fallout from Cambridge Analytica and other scandals.)

To really get a sense of how APIs work, let’s do a deep dive into two: the Java API, which Java developers use to interact with the Java platform, and the Twitter API, a public API that you would use to interact with the social networking service.

The Java API

The Java API is a library of software components available “out of the box” to anyone who has installed the Java Development Kit. These components implement common tasks and generally increase productivity because programmers don’t have to start from scratch every time. One of the basic components used in software is something called a List, which, as you might expect, keeps track of a list of items. The Java API defines what you can do with a List: add items, sort the list, determine if an item is in the list, etc. It also specifies how to perform those actions. In order to sort the List, you need to specify how you want the List sorted: alphabetically, numerically descending, brightest to dullest color, etc.

The Twitter API

The Twitter API is a web-based JSON API that allows developers to programmatically interact with Twitter data. Unlike the Java API, which is included in the Java Development Kit, the Twitter API is a web-based API. It must be accessed by making requests over the Internet to services that Twitter hosts.

With a web-based API such as Twitter’s, your application sends an HTTP request, just like a web browser does. But instead of the response being delivered as a webpage, for human understanding, it’s returned in a format that applications can easily parse. Various formats exist for this purpose, and Twitter uses a popular and easy-to-use format called JSON. (If you’re not familiar with JSON, you might want to spend a few minutes reading up on it here.)

One of the basic elements in Twitter is a tweet. The Twitter API tells you what you can do with tweets: search for tweets, create a tweet, favorite a tweet. It also tells you how to perform these actions. To search for tweets, you need to specify your search criteria: terms or hashtags to look for, geolocation, language, etc.

API design

API design is the process by which the “what” and the “how” of an API are formulated. As with anything else that can be created, varying levels of thought and care are put into API design, resulting in varying levels of API quality. Well-designed APIs have consistent behavior, take their context into account, and keep the needs of their users in mind.

Consistent behavior within an API greatly impacts the speed at which it can be learned and the likelihood of programmers making mistakes when using it. Generally, APIs that perform similar actions should behave similarly, regardless of their technical differences. For an example of an inconsistent API, let’s look at the two ways to add an item to a List in Java:

Even though the two methods of adding items to a list do the same thing, their return types (boolean and void) are different. Developers using this API now have to keep track of which method returns which type, making the API harder to learn and its usage more error prone. It also means the code that uses these methods becomes less flexible, because it has to change if you want to switch the way you’re adding elements.

Taking context into account is another form of consistency, although it has to do with factors external to the API. A great, non-software example of this is how the rule of the road right hand traffic or left hand traffic influences car designs for different countries. Car designers take that environmental factor into account when locating the driver seat on the right side or left side of the car.