# Demystifying the API

Many 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 other 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 itself, 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.

## Simplied programming through an API

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

```
#include <stdio.h>

int main() {
 printf("Hello, World!");
 return 0;
}
```

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

```
print('Hello, world!')
```

Of course, there's usually some complicated code to create the API itself, [as demonstrated by the Lua example](https://www.lua.org/pil/26.1.html) 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 users through an API.
By providing an API, features can be provided to users without requiring them to learn complex commands, and without exposing sensitive data.
For instance, if you run a support forum or chat server, then you might want to permit people to know the current number of other users (because the more users present, the greater chance of receiving an answer to a support question), but not the usernames or activities of each.

A real life example is the release API implemented by the open source Git host [Gitlab](https://opensource.com/article/19/10/how-gnome-uses-git).
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 from within the Gitlab web UI, many developers prefer to automate the process entirely so 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 obtaining 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 into their existing processes.

## What is an API key?

In the Gitlab example, you may notice that a key is required.
An API key serves the same function as a user name and password in a wholly interactive interface.
Because it's expected that the two entities interacting through an API are computers, it would be over-complex to present a user name 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, which can be included in the code being 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 non-open 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 of user name 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.

## The difference between an SDK and an API

An API abstracts the programming functions of an application from the tools being used to control it.
An SDK (Software Development Kit) are 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 programmer to build tools *around* a complex application, without having to understand too much about how the application itself works.
Other times, an API safeguards important or sensitive data while still allowing access to other data.

In proprietary applicaitons, 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 of indicating to other developers what functions are most important for the most common use-cases.
For instance, if you want to develop a [Qt](http://qt.io) application, you probably want to use the Qt SDK even though Qt itself is open source, because when people talk about developing Qt apps, they mean that they're using Qt libraries to develop an application of their own.
If you wanted to actually 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 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](http://jboss.org) and [3scale](http://3scale.net), while others are written in Python using [Flask](https://opensource.com/article/19/11/python-web-api-flask) or [Django](https://opensource.com/article/19/11/python-web-api-django) or [Pyramid](https://opensource.com/article/18/5/pyramid-framework).
Still others are written in Ruby, Perl, Lua, C, C++, [dotnet (.Net)](https://opensource.com/article/19/9/getting-started-net), and nearly any other language you can think of.

## RESTful API

In his dissertation, Dr. Roy Fielding described a style of API he called **Representational State Transfer**, better known as [REST](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).
There are many subtleties as to 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 necessary data to complete an interaction.

If you have written an API that provides a user's bank balance, then your API must accept the user name and password (or API key), relevant bank account, and whatever the command is to retrieve the 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 a balance of an account 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 separation of client and server.
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.
That means a phone app and a Terminal-based application can both be developed for the *same* server without modification, because the API provides a consistent interface.

## 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](https://jsonapi.org) 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!

You are viewing proxied material from sdf.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.