What is an API?

API stands for "Application Programming Interface". Separately, you may already know what these terms mean:

• Application is a piece of code that runs and does something.
• Programming means providing instructions for performing a task.
• Interface is the trickiest of the three terms! An interface dictates how two things are allowed to interact with each other.
• For example, a car. A car's interface are the steering wheel, the pedals, and the knobs in the dashboard. That is the interface between the car and the driver.
• Another example, a restaurant. The server (waiter) may be thought of as the interface between the customer and the chef.
• Let's give one more example with code!

Code example for interface

Let's say you've got this file:

_db = {}

def add_post(title, body):
    _db[title] = body


def find_post(title):
    return _db[title]

In this file (which we'll call the server) you have a "database" called _db, and two functions. If we assume that the underscore in front of _db means that you shouldn't access the _db variable directly, that leaves you with two options for "interacting" with the "database": add_post and find_post.

So if you wanted to write another file that uses this database, you might do something like this:

from db import add_post, find_post

add_post("Hello", "Hello, world!")

print(find_post("Hello"))

This file (whick we'll call the client) is using the db file, and the way it does that is through its exposed interface.

You could import _db and do things like modify an existing post, or delete a post. But the exposed interface, which is what you're expected to use, does not allow this functionality.

What is a web API?

A web API is exactly like this code file, but instead of the client and server being two code files, they are a bit different. The server is a program connected to the internet which accepts data over the internet from the client.

In this data is what does the client want.

So the client might sent a request asking the server to create a post, or a different request asking the server to return information about a post.

Here's a request that a client might send the server asking for a post:

GET /post/Hello

This request has a few different bits of information that allow the server to interpret what the client wants.

As the backend developers, or developers of the server code, we can code the server program to respond however we want in response to these bits of information.

In this specific case, the request has these bits of information that we can use in the server:

• The method, GET.
• The endpoint, /post/Hello.
• The request body (empty).
• The headers (empty).

We can code the server so that when it receives a GET request with the endpoint /post/Hello, we return information about a post with title Hello.

Or we could code the server in a completely different way, such that when we get this request we create a new post with title Hello. It's up to us backend developers!

But there are standard ways of doing things which make your API much more intuitive to other developers.

For example, GET should be used to retrieve information. Other methods, like POST, are used to create information. There are many others, like DELETE or PATCH (for updating). But the main thing is: how did we code the server to respond?

What is in a web request?

A client sends information to a server in the form of a web or HTTP request, and then the server responds with an HTTP response.

In an HTTP request there are a few key bits:

• The method, such as GET or POST. Methods have meaning, and usually servers will respond in predictable ways to each method. For example, GET tends to be used to retrieve information and POST tends to be used to create information. If the server you code uses POST to retrieve information, that will be seen as weird and un-intuitive. Also, some methods have certain restrictions, such as no request body being present in GET requests.
• The endpoint, which is where the request is sent. The client might send the request data to this address: https://api.com/post/Hello. Here the "endpoint" is /post/Hello. This is part of the request, and the server will see that and can do something with that information.
• The request body, which is usually JSON. The client can use this to send more information to the server.
  • For example if the client wants to create a social media post, it might send a request that looks like this: POST /post {"title": "Hello", "body": "Hello, world!"}.
• The request headers, which are key-value pairs. This is also used to send extra information to the server. Most header names are standard, so for example you'd use Content-Type to tell the server that you're including JSON in the request body. Or you can use Content-Length to tell the server how long the request body is.
• In the endpoint you can also include query string arguments. These are part of the address to which the client sends the request, and these are often used to send extra (usually optional) data to the server.
  • For example: https://api.com/post?sorting=most_likes includes the sorting = most_likes query string argument, which could conceivably be used by the server to return a list of all existing posts, sorted by those with the most "likes" first. Again, this is up to the server's implementation.