What is an API?

Contributed by: Name, ORCID iD
Original published date: Note: This page is currently being drafted and open to contributions from the community.
Last modified: See Github page history

Suggested Citation: Author Name, “What is an API?,” Digital Scholarship & Data Science Essentials for Library Professionals (2024), [DOI link tbd]

Introduction

Any time you write code you are using an API! When you write print(“Hello world”) in Python, the Python Standard Library API is the contract that guarantees the words Hello world will appear on the screen. When you do the same in R, it’s the API of R’s base package that you are using. Other languages’ APIs use other words for the same function (printf, echo, format are some common ones) and may have subtly different interpretations.

In many ways an API is like a restaurant menu: the menu sets out the acceptable ways of interacting with the kitchen by specifying what dishes you can order with a brief description of what to expect from the dish, and how much you will have to pay. Items on a menu don’t include a detailed description of their implementation (a recipe), only enough information for the diner to make an informed choice about what they want to eat. If you’re confident you know what you’re doing you can order off-menu, but the results aren’t guaranteed to be what you expect, because there is no documentation of those expectations for the kitchen to refer to.

API is an acronym for Application Programming Interface. Where a GUI (Graphical User Interface) provides a consistent way for humans to interact with an application, an API provides a consistent way for code to interact with other code. APIs set clear expectations that are necessary for

Generally “API” can be applied to any consistent interface provided by one computer program for other programs to use, but the most common you are likely to encounter in Digital Scholarship work are:

  • A set of functions/variables available through a code library, and their expected behaviour
  • A set of HTTP URLs provided by a system/service, and the expected behaviour when those URLs are requested from the server by another program
    • E.g. the DataCite API defines a URL https://api.datacite.org/dois which returns a list of all published DataCite DOIs to the requester, formatted as JSON, and when followed by the parameter ?prefix=10.23636 will filter the returned list to only include DOIs with that prefix

Both of these examples share some important elements. They specify:

  • What the programmer must do
  • What response the programmer can expect and in what format
  • What side-effects the programmer should expect

Let’s look at those two types in more detail through this lens.

Example 1: a Python library API

The re module mentioned above includes a function called search with the following documentation:

re.search(pattern, string, flags=0)

Scan through string looking for the first location where the regular expression pattern produces a match, and return a corresponding Match. Return None if no position in the string matches the pattern; note that this is different from finding a zero-length match at some point in the string.

Todo
  • Break down this definition into how it describes different parts of how the programmer can use this function
  • Maybe move this section to the hands-on activity?

Example 2: a HTTP API

Todo
  • Worked example of a HTTP call (e.g. the DataCite endpoint mentioned above)
  • A diagram will be very helpful!
  • Should this include example Python code or is that too much detail?

Glossary

  • Argument
  • Call
  • Client
  • HTTP
  • Library
  • Parameter
  • Request
  • Return
  • Server

Relevance to the Library Sector (Case Studies/Use Cases)

Many (most?) systems that we use every day have APIs. Knowing what these look like and how to use them in general is an important first step in being able to write software that accesses those systems to do much more than you could do with your own code alone. This becomes even more powerful when you can write “glue” code that brings together parts of two or more APIs

Hands-on activity and other self-guided tutorial(s)

  • Something involving Postman?
  • Exploring published API documentation? E.g. DataCite API docs allow you to run test queries from the web page

Taking the next step