API

Application Programming Interfaces (APIs) enable communication between two or more computer programs or parts of a system, by providing a shared language between different components or types of software.

Overview
An application programming interface is a type of interface that is designed for other software as the interface's intended users.

In computing, an interface is a "shared boundary or connection between two dissimilar objects, devices, or systems through which information is passed.” [12] The purpose of an application programming interface is to make it easier to pass information across the boundary between one computer program and another.

Because APIs are a fairly abstract concept, it can be helpful to think of them as analagous to a more familiar and concrete type of interface that many people interact with daily: user interfaces. User interfaces are the boundary where humans and computers meet. They are designed with the needs of humans in mind. User interfaces seek to translate information from the computer so that it is accessible and actionable for a human user.

The purpose of a user interface for software is generally twofold:

to provide a representation of a software application's functionality, presented in a way that the intended user can understand

to enable the user to perform actions with the software.

For example, graphical user interfaces (GUIs) for computer operating systems (software such as Microsoft Windows, Mac OS, or Linux) commonly provide a pictorial representation of a computer’s file system as a physical desktop and folders, with a menu of options for available actions. Other widely-used GUIs, such as email applications or web browsers, represent complex computing operations with a simple graphic indicator that a person can easily interact with, such as the “Send” button for an email, or a web browser's “Back” button. These examples demonstrate how the user interface for software can enable a user to perform actions without requiring that they interact with or know anything about the underlying code that is required to make their actions possible.

Application programming interfaces perform a similar role, except that their intended user is other software. Accordingly, APIs employ representations that are well-suited for interpretation by software. APIs provide an interface that represents a software's functionality in a way that other software programs and services can understand and interact with. They enable other software programs and services to access information and to perform actions. APIs translate the complex details of software into a condensed, clearly-defined syntax that other software can use to formulate complex computing operations as fairly simple requests, without needing to interact with the underlying code.

Types of APIs
There are many different types of APIs at all levels of computing, such as APIs for computer hardware, for operating systems, or for software libraries. [2] In each of these contexts, the purpose of an API is to describe and provide access to particular functionality without requiring compatibility of the underlying technologies or interaction with the actual code.

Software Library API Example: pandas
The pandas data analysis library created for the Python programming language provides an example of a software library API. [13] The pandas library provides access to software tools called objects, functions, and methods. These tools are detailed, purpose-built blocks of code that can be included and used in a Python program simply by referencing the name of the tool, rather than including all of the actual code. Including the object and method syntax in a python program prompts the pandas library to apply the relevant blocks of code when the program runs. The pandas API thereby supports creating python programs that perform complex data analysis operations in very few lines of actual code.

For example, a Python program might use the pandas API to import a data set contained in a file named "data.csv" via the "read_csv" function, and to represent the data as a “DataFrame” object, using the syntax: df = pd.read_csv('data.csv'). The dataframe object can then be queried and analyzed using additional functions and methods. For example, the “DataFrame.info” method can be invoked using the syntax: df.info to print a summary of the data: column labels, number of values in each, and data types represented.

Examining the source code for the info method shows the programming logic that is invoked via the df.info syntax. The pandas API provides a shortcut to the functionality enabled by this detailed code.

image: [many lines of computer code from the pandas "info" method "pandas.DataFrame.info — pandas 1.5.1 documentation". pandas.pydata.org.]

Web APIs
Web APIs connect software applications and services via the internet. These are one of the most common types of API within software development, and are integral to the operations of information providers and services on the Web.[1]

Since the early 2000’s, there has been enormous growth in the use of Web APIs across all sectors of technology. These began with software and service integrations to support commercial activities such as online retail and business analytics and logistics software, and expanded further into most internet users’ daily online activities with the rise of social media after 2006.[1]

Because of the widespread usage of Web APIs, the broader term “API” is frequently used to refer to this type in particular. [4] However, the specific function of Web APIs is to provide an interface for communication from disparate data providers and consumers across the internet. Web APIs enable many of the functions that are hallmarks of how people use the internet in 2022. News aggregators, social media, and financial services all rely on these APIs to share data from one source into other locations and services on the Web.[3] [5]

Within Web APIs, the most common type is the REST API. These are built to “conform to the constraints of the REST architectural style and allow for interaction with RESTful web services”. [16] The REST architecture (REpresentational State Transfer) provides standardized operations for how computer systems transfer data on the Web. Following REST guidelines enables APIs to be easier to build, as well as scalable and flexible in how they interact with other systems. [17]

icon of a mobile device superimposed with social media icons Social Media by Puchongart from Noun Project

REST API Example: iNaturalist and Google Maps
The iNaturalist online resource provides an example of how Web APIs work. The iNaturalist web site, as well as iPhone and Android apps, allow users to upload “observations” which “record an encounter with an individual organism at a particular time and location.” iNaturalist uses the Google Maps API to pull in and display map data, and also to associate locations submitted in users’ observations with coordinates so that new observations are placed and displayed on the map. [14]

[screenshot from inaturalist web app, showing species annotations added near Portland Art Museum "Observations". iNaturalist data for location: Portland Art Museum 1219 SW Park Avenue Portland, OR 97205]

Observations data are recorded via the iNaturalist API: “a set of REST endpoints that can be used to read data from iNat and write data back on the behalf of users.” [15] The screenshot below shows the documentation for the API endpoint that adds new observations submitted by users into the iNaturalist database. An endpoint is the URL where an API request is sent for interacting with data on a server.

[screenshot of the iNaturalist API endpoint for posting new observations to the database]

Documenting APIs
The purpose of API documentation is to define what an API does and how it works, so that developers and other users can integrate the API functionality with their own software and systems. The goal is to communicate what is possible with the API, and to demonstrate concrete usage scenarious through use cases and code examples. [7]

[icon of a checklist with checkmarks added to points in the list Checklist icon by ifan kurniawan from NounProject]

For example, documentation for REST APIs should define essential features for this type of architecture: [6]
 * 1) Authentication instructions
 * 2) Resources, endpoints, and methods: the types of information available, and how they are accessed, and allowed interactions for a particular resource.
 * 3) Parameters: input options that may be included to determine the response received from a request
 * 4) Examples: requests with responses, to show expected output according to options for format and structure

Challenges in API Documentation
At minimum, API documentation needs to include an API reference, which outlines all operations included in the API, with usage requirements such as syntax for each operation. Software tools can generate an API reference automatically by extracting this information directly from the API code. However, research into usage of reference documents created this way has indicated that they are insufficient to accomplish the goal of communicating to developers a complete understanding of the API and how to use it.[8]

Notable Examples of API Documentation
The documentation sites listed below demonstrate key features recommended for effective API documentation:

Offer guides at different levels of detail: “Quickstart” to walk an experienced developer through basic setup steps; “Getting Started” to provide more details and explanation for beginners.

Clarify unfamiliar terms with a comprehensive glossary

Use plain language and simple, clear explanations for API concepts and terms

Demonstrate real-world applications in relation to specific, recognizable use cases

Include code snippets to illustrate examples

Follow best practices for layout and design, with streamlined navigation and consistent page formatting

icon of an award ribbon with a checkmark in the center Stripe API Reference

Twilio REST API Documentation

Dropbox API Documentation

Quickstart for GitHub REST API