What Is an API?

We live in a technology integrated world. We communicate, receive information, and exchange data in ways that have become ever faster and increasingly more accessible across all domains of human living. From smart phone notifications to automated lighting systems to Google Maps, E-commerce, and IoT devices, the technology that makes all this possible are APIs.

API stands for application programming interface and it’s a way for two software applications to communicate with one another using a standard set of definitions and protocols.

A common use case for APIs are the web services that you use every day. For example, you have probably used an online document editor like Google Docs or Word in Microsoft 365 at some point in your education or career. Each of those apps are using an API to interact with the web server. Every time a document is created, read, edited, deleted, shared, and etc., the API is used to perform those actions.

Another example of APIs in use is e-commerce. If you ordered ice cream from an online website it might seem like there’s a single application handling the sale but there are likely many little apps running independently, yet collectively, as microservices. One handles user log in, another handles the payment, another processes the delivery time, another is in charge of product reviews, and so on. Each little program has its own API that allows other microservices to connect, communicate, and interact with each other.

Basically, APIs are the interface between a client and a web server. The client may be an end user or it may be another web application.

The API receives the incoming requests, tells another system what to do, and then returns a response back to the client, often in JSON format. To determine how to handle a request, the API inspects the HTTP request method.

HTTP Request Method

APIs determine what action to perform based on the HTTP Request Methods it receives from the client. The most common HTTP Methods are GET, POST, PUT, and DELETE.

GET is used to read data. POST is used to transfer data. PUT is used to update existing data. DELETE is used to delete data.

A standard HTTP request could look like https://example.com/api/ice-cream-inventory/search?name=peppermint and would be broken down into its individual parts:

• https:// as the protocol to be used when requesting data
• example.com as the host where the request will be sent
• /api/ice-cream-inventory/search as the path so the API knows where to perform an action
• ?name=peppermint as an optional parameter

The GET method in this example is not seen in the URL itself but is included in the HTTP headers of the request. HTTP headers contain additional information about the request and response such as request type, authentication, cookies, and so on.

When an API receives a request, it processes that request based on the request method and returns a response, usually in a JSON format, with a status code that is associated with that response.

HTTP Status Codes

HTTP status codes tell the client the result of the request. Was it successful? Was there an error? What type of error occurred? There are many different status codes to represent different results.

When the request is successful, you receive the 200 OK response.

A few of the common errors that occur include 401 Unauthorized when you do not include authentication when it’s required, 403 Forbidden if you do not have access to the specified path/request type, or 404 Not Found when the API cannot find what you’re looking for.

You may also see a 500 Internal Server Error when the server encounters a situation that it doesn’t know how to handle.

Security

Security is of high concern as the API is exposing the application publicly. Most commercial APIs have security features in place for authentication and authorization, secure communications, and best practices regarding data governance.

These things might include API keys, web tokens, and two-factor authentication that restrict user access, rate limiting to restrict the number of API calls made per hour, and enforcing TLS (transport security layer) to encrypt data in transit between the client and the server.

API Examples

There are an enormous number of APIs in existence. Below are a few interesting examples to check out. Maybe you can create your own app from one?

The Star Wars API (SWAPI) contains all the Star Wars data you’ve ever wanted, including Planets, Spaceships, People, Films, and Species. Visit their documentation page to learn more about the resources available and how to consume them with HTTP requests.

An example GET request to the Star Wars API is shown below. This response returns information on the Death Star.

https://swapi.dev/api/starships/9/

The Chuck Norris API is a free API that returns Chuck Norris facts. These are satirical factoids that make absurd claims about his toughness and attitude such as “Chuck Norris does not do pushups. He does pushdowns.”, or “Chuck Norris does not sleep. He waits.”

An example GET response from the Chuck Norris API is shown below.

{
  "categories": [],
  "created_at": "2020-01-05 13:42:29.296379",
  "icon_url": "https://assets.chucknorris.host/img/avatar/chuck-norris.png",
  "id": "785KRzs7Ta62BcXKC5rQYQ",
  "updated_at": "2020-01-05 13:42:29.296379",
  "url": "https://api.chucknorris.io/jokes/785KRzs7Ta62BcXKC5rQYQ",
  "value": "Chuck Norris brushes his teeth with a machine gun and flosses with a lightsaber."
}

The Dad Jokes API is another API to check out. It provides short jokes or puns that are presented as one-liners or as a question-answer. Users need an API key from RapidAPI to access the jokes. Below is a sample response.

"success": true,
"body": [
	{
		"_id": "5f80ccd641785ba7c7d27c18",
		"type": "general",
		"setup": "What do you call a fashionable lawn statue with an excellent sense of rhythmn?",
		"punchline": "A metro-gnome"
	}
]

Summary

In this post we looked at what APIs are and how they function. If you’re interested in creating your own, check out the FastAPI reading list to create an API for an ice cream inventory app.

Or visit the WWW reading list to find out more about that thing they called in the 90s, the world wide web.