What is an API?

Many of the applications you run on your computer have a user interface, usually featuring buttons to click, icons to drag, and text fields to type into. Some applications use the terminal as an interface, so a user can type commands instead of clicking buttons or dragging icons. An application programming interface (API) is also an interface, but it's one meant for applications instead of users.

Of course, all computers are ultimately meant for a user, but an API makes it easy for a human to write code that, in turn, controls the application behind the API. For humans, an API would be an inefficient and indirect means of using an application, but for computers, an API is a convenient way to send signals and get meaningful data in return. An API can be accessible locally or over a network, the largest being the internet, and they can be designed to accept input from any number of programming languages and protocols.

APIs are commonly used for video game design and modding, extending complex applications, and scraping data from and interacting with websites.

Simplified programming through an API

One advantage of an API is that it can hide complex code requirements from the user. For instance, this is a simple C program to print "Hello world" on the screen:

#include <stdio.h>

int main(int argc, char *argv[]) {
    int i;
    for(i=1;i<argc;i++) {
        printf("%s\n",argv[i]);
    }
    return 0;
}

An API written to produce the same output could drastically simplify the code. For example, here is an imaginary API (looking suspiciously like Lua):

cprint(hello_msg)

Of course, the code to create the API is usually complicated, as demonstrated by the Lua example that inspired this simple example, but the end user doesn't have to deal with that. The only thing the end user sees is a simplified programming language that provides access to the results of very complicated computations.

Simplified queries through an API

Similarly, instructions for specific actions or queries for information can be provided to end users through an API. An API enables people to use features without requiring them to learn complex commands nor exposing sensitive data. For instance, if you run a support forum or chat server, you might want to share the number of other users (e.g., the more users present, the greater the chance of receiving an answer to a support question), but not their usernames or activities.

A real-life example is the release API implemented by the open source Git host GitLab. GitLab has a rich API to help developers mark their recent software builds for official release. While it's possible for programmers to create a release build within the GitLab web UI, many developers prefer to automate the process so that there's no need to manually click through option screens. GitLab makes it possible to send commands over HTTP (using the POST method). Here's an example:

$ curl --header 'Content-Type: application/json' \
--header "PRIVATE-TOKEN: example_token" \
  --data '{ "name": "Release", "tag_name": "2.4", "description": "Fixed Makefile.am" }' \
  --request POST https://gitlab.com/api/v4/projects/trashy%2Ftrashy

There's much more to the GitLab API, including getting information about tags and releases, deleting releases, updating releases, and so on. Because the API uses standard HTTP methods, it's easy for developers to use and integrate it into their existing processes.

What is an API key?

In the GitLab example, you may have noticed a key is required. An API key serves the same function as a username and password in a wholly interactive interface. Because the two entities interacting through an API are expected to be computers, it would be overly complex to present a username and password field, like the one you see when logging in to check your email, for instance. Instead, the human programmer is issued an API key that can be included in the code written to interact with the API.

Obtaining an API key differs depending on who wrote the API you're writing for. GitLab, for instance, supplies an API key in its Access Tokens settings panel, while (the closed source) Twitter service offers API keys through a developer subdomain. Because API keys are generally considered developer tools, they are rarely issued to every user by default but reserved for advanced users upon request.

API keys have the same advantages as usernames and passwords: they regulate access to sensitive data. Just as an API allows one application to selectively reveal information based on what calls are provided through the API, an API key allows exceptions to be made based on whether the requesting call has a valid API key.

Differences between SDKs and APIs

An API abstracts the programming functions of an application from the tools used to control it. A software development kit (SDK) is the literal programming functions of an application.

In open source, an API is often provided for convenience or security. Sometimes, an API makes it easy for a programmer to build tools around a complex application without having to understand too much about how the application works. Other times, an API safeguards important or sensitive data while still allowing access to other data.

In proprietary applications, an SDK serves as the "most open" part of the code base, and it often costs money to legally get access to it. It's usually the part of a product that developers pay for so they can develop with it.

Technically, an SDK isn't needed in open source. The source code is available for anyone to use and alter directly. However, some open source projects provide an SDK as a way to indicate to developers what functions are most important for the most common use cases. For instance, if you want to develop a Qt application, you probably want to use the Qt SDK even though Qt is open source, because when people talk about developing Qt apps, they mean they're using Qt libraries to develop an application of their own. If you wanted to develop Qt itself, you wouldn't use the Qt SDK, because you'd essentially be writing the SDK.

The separation between an SDK and an API can blur in some cases, but generally, an SDK provides access to libraries, while an API uses those libraries to produce a result upon command.

How is an API created?

An API is an interface, meaning that it exists to facilitate interaction. In computing, an interaction often consists of a request and an answer. If you write code that listens for instructions over a protocol other than (or in addition to) direct human intervention, then you have probably created an API.

An API can be written in any programming language. Many are written in Java with the assistance of "middleware" like JBoss and 3scale, while others are written in Python using Flask or Django or Pyramid. Still others are written in Ruby, Perl, Lua, C, C++, .NET, and nearly any other language you can think of.

What is a RESTful API?

In his dissertation, Dr. Roy Fielding described an API style he called Representational State Transfer, better known as REST. There are many subtleties about what qualifies as a RESTful API, but one of the most important is the idea of statelessness: The server (the side of the API taking action based on prompts received from the client) must store no user data and must receive everything it needs from the client. That means a RESTful API must have calls designed to provide all data necessary to complete an interaction.

If you have written an API that provides a user's bank balance, then your API must accept the username and password (or API key), the relevant bank account, the command required to retrieve the bank balance, plus any options (such as currency type and language). All of this information must be provided with each request because, after each request, the server returns to its default no-knowledge state, as if it had never received a request from anyone. Even if a user is performing related tasks, such as getting an account balance before transferring money from that account to another, the server requires all credentials and specifics to be transmitted as part of the request.

There are many benefits to a RESTful API, not the least of which is client and server separation. Because the server contains no user data and is not dependent upon a specific type of interface, unique clients can be developed by many developers. This means a phone app and a terminal-based app can be developed for the same server without modification because the API provides a consistent interface. It's no coincidence that most terminal commands function the same way. Even commands that allow for configuration files that store persistent options still provide either environment variables or command-line options for you to specify important parameters, inputs, and outputs. A RESTful API is a lot like a command that you run on some other system.

Taking advantage of an API

If you've never used an API, try using one for something simple, and then take notes about what you like about it and what its limitations are. If you're a developer, read up on API design and try writing an API. Like open source itself, the concept of an API has helped computing become more flexible, more accessible, and more efficient. Get familiar with it and, as always, keep it open source!