Application Programming Interface (API)

An application programming interface (API) allows users to interact with the functionality contained in code libraries, so that the programmer's do not have to dive into the details of that library.

What's an API conceptually? The waiter metaphor is often used (spoiler: the waiter is the API):

  • You request a dish from a menu: the request
  • De waiter is a messenger that takes the request to the kitchen
  • The kitchen prepares the dish
  • And the waiter comes back to you and serves the dish: the response

Examples:

  • Web API: An API that's accessible from servers that accept requests via HTTP.
  • Web API endpoint: The location of the code library.
  • REST API: The design of the URL style that's used to expose the API's functionality.

REST

RESTful APIs are the most common APIs nowadays. But what is a RESTful API?

REST: Representation State Transfer

  • Client: asks another computer for data or to take an action
    • The client in the restaurant
  • Server: needs to do the work
    • The kitchen
    • Will respond in JSON

Type of requests

CRUD, the types of operations:

  • Create
  • Read
  • Delete
  • Update

GET (read)

  • GET requests work via standard URLs in RESTful APIs
  • Loading a website is a GET request to get data from some other computer
  • So we are not asking to perform a task
  • There is no creating, updating, or deleting data
  • This is the most common way to interact with an API

Let's say you have a type of object called a "user". You could query the API with a listing URL: show me all users. This is like asking for the general menu.

Example of a listing URL: HTTP GET http://website.com/api/users

After learning about which users exists, you can query a specific user: HTTP GET http://website.com/api/users/1

POST (create)

  • A post does not go through a standard URL, but does use a URL as the endpoint
    • So this asks a computer to perform a task, namely to make a resource
  • It also returns information about the newly created resource, so you can follow up with a GET request

In the kitchen metaphor, asking the chef to make a new dish is like submitting a POST request. The chef will make the dish and let the waiter know that it can be picked up.

Example: HTTP POST http://website.com/api/users to create a new user. Let's say this creates user 353, we can then GET this user's information using HTTP GET http://website.com/api/users/1/.

DELETE

  • Does not use a standard URL, but does have a URL as the endpoint
  • Ask a computer to delete a resource or a list of resources
  • Caution: restrict usage! You probably don't want regular users to delete lists of resources (like deleting all users)

In the kitchen metaphor, it may be that you are charged for something that you do not eat. In that case you send the waiter back to the register to delete the erroneous entry.

Example (notice the specific URL instead of a listing URL): HTTP DELETE http://website.com/api/users/1

PATCH (partial update/modify)

  • Does not use a standard URL, but does have a URL as the endpoint
  • Does not update the whole resource, but only a piece of a resource
    • E.g. do not update a user, but only it's first name
  • Not all browsers and not all frameworks support PATCH requests
    • These fall back to PUT requests

In the kitchen metaphor, you may be correctly charged for the right pizza, but the price may not be the right one.

Example: HTTP PATCH http://website.com/api/users/1

PUT (update/replace)

  • Does not use a standard URL, but does have a URL as the endpoint
  • We update a whole resource (cf. patch)
  • Some APIs make a resource when you submit a PUT request for a non-existing one

In the kitchen metaphor, you may be charged for a steak instead of a pizza. Here we want to update the whole resource.

Because PATCH is often not supported, we typically just rely on PUT.

Example: HTTP PUT http://website.com/api/users/1

How to consume APIs

APIs typically return either JSON or XML.

JSON is quite human readable, but a downside is that you do not get a contract about the value types that are returned. With XML on the other hand, we do, but is less lightweight.

Browsers use JavaScript for API requests. Servers can use any any language that runs on their OS and supports web requests.

Responses

Everything in the 200 range is typically for healthy sponses.

  • 200: OK
  • 201: Created (typically for a POST request)
  • 202: Accepted (but server is busy)

300 range, redirect sponses:

  • 301: Moved permanently
  • 302: Found, but temporarily moved

400 range, client responses (something on our end are not right):

  • 400: Bad request
  • 401: Unauthorized (you can't go directly into the kitchen, ask the waiter and use the right API key!)
  • 403: Forbidden
  • 404: Not found
  • 405: Method Not Allowed (e.g. you can GET but POSTing is not allowed)

500 range, server response:

  • 500: Internal Server Error, you cannot do anything about this one as a client; the kitchen burned down.

Links: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/418

API Keys

Typically acces tokens are needed for authentication. And these access tokens are typically generated with an API key.

Keep them secret! Also see best practices below.

Example:

It's a best practice to load in private API keys as an environment variable. In Python, you can do this using the os module:

import os

API_KEY = os.getenv('PROJECT_API_KEY')

Where "PROJECT_API_KEY" is an environment variable. (E.g. in bash $PROJECT_API_KEY=1234).

Another strategy is to define keys in a .env file, but enforce it is never pushed to the code repository using .gitignore. In many languages you'll find a dotenv package for this workflow. This way you don't have to manually specify environment variables. For example, in Python you can do the following:

import os
from dotenv import load_dotenv

# This reads the entries in .env and
# loads them as environment variables
load_dotenv()

API_KEY = os.getenv('PROJECT_API_KEY')

Now you can safely use your API key:

import requests

response = requests.get(f"https://example.com/api/?api_key={API_KEY}")

If you take this strategy, make sure you don't print(API_KEY) in a notebook and publish the output....

Best practices

Requests:

  • Don't request things you don't need, including additional fields
  • Filter in the API query as much as possible instead of requesting a lot and then parsing the output

API keys:

  • Don't store the API key in your code. Instead, keep them in environment variables outside your application, that you can however read in your code.
    • E.g. see os.getenv() in Python, or the dotenv package for NodeJS or Python.
  • Store your credentials on the backend of your application and do the API request there
    • Safety: avoid having credentials on client side, because they can be reverse engineered
    • But also you do too many requests if you let each client do API calls, instead of doing an API call once on the server and serving the results to the client
  • Do not have any credentials ever in your repository. Even if you delete them, they can be somewhere in the history.
    • So also not private repositories, just don't do it!
    • Add sensitive files to the .gitignore to be sure; implement a hashing strategy, e.g. git-secret or git-crypt
  • If you suspect a breach, regenerate the API key.