In this article, I'm going to cover what APIs are in general and provide an in-depth real example that you can follow along with.

What are APIs?

On the most basic level, application programming interfaces (APIs) are just lines of code that instruct how two separate software components transmit information to each other. When an API function is called, two processes occur. The first process is Software Component A sending a request to Software Component B, and the second process is Software Component B sending a response to Software Component A.

Here's a simple example: let's say that I'm tracking my daily body weight and storing the data in a simple text file. If I want to automate the process of calculating my weekly averages and automate the process of storing the averages in the text file, I can do so with a simple Python script. Using built-in functions in Python that can send requests to files, and receive responses from files, I can allow my Python script to read the contents of the text file, calculate the weekly averages, and then write those weekly averages to the text file.

The above example of an API uses local software components stored on a singular computer. Although, usually when people refer to APIs, they're referring to web APIs. Web APIs allow for the transmission of information between separate software components on separate computers over a network of networks of computers (aka, the internet).

How to Implement and Use APIs

I'm going to walk you through the full process from finding an API to implementing the API in code.

Finding an API

In my example, let's say that I run a blog dedicated to cats, and I want to add a button on my blog that displays a random picture of a cat upon being clicked.

To start, I'm going to simply search "cat API" on Google.

The first result on Google is The Cat API. To find out the gist of this API and how to use it, I'm going to click on the Documentation tab.

Every API should have documentation explaining the API, how to implement it, API methods, and terms of service.

In The Cat API documentation, I see that this API does involve sending images of cats as API responses. The next step is to review the terms of service.

Reviewing the terms of service

In reviewing the terms of service for an API, there are 5 main factors you want to clarify:

After reviewing the documentation for The Cat API, here's what I've gathered:

• An API key is not required if I request no more than 10 images per API request. Although, obtaining an API key is free and allows me to receive up to 100 images per API request, and allows me 10,000 API requests per month.

• API requests and responses are sent over HTTPS.

• CORS is not enabled for this API.

• I can make 10,000 requests per month in the free plan, 100,000 requests per month for $10/month, and unlimited requests per month in their "enterprise" plan which is volume-based pricing.

• If you're using the free plan, they require you to only implement their API in non-monetized applications. However, if you charge users to use an application that involves the implementation of The Cat API, then you must select at least the paid plan of $10/month.

All in all, I feel safe using this API, and my intentions of using it don't violate their terms. Even though CORS is not enabled for this API, we can work around this by using a proxy server.

Make an API call

The next step is to read the API documentation to obtain the URL that you send a request to, and the parameters that you can include in the request.

For The Cat API, I didn't sign up for an API key, so I'm going to use the URL that sends a request for 1 random image of a cat.

Notice how the URL for an API request looks very similar to a URL for a webpage that displays HTML. The main difference is that a URL for an API request has "api" instead of "www". This tells the server to serve an API response in the form of a data file (usually a JSON file format) as opposed to serving a webpage that displays HTML.

Also, take note of how parameters are added to an API URL to specify a request. For The Cat API, the base URL to make a request is api.thecatapi.com/v1/images/search. This request will return one random image of a cat, but we can modify the request by adding parameters to the URL. For example, there's a parameter "limit" that we can set to specify how many images we want in that request, "breed_ids" that we can set to specify the breed of the cat(s) in the images, etc. Depending on the API, some parameters are required to define, but there's usually a plethora of parameters that are optional and you'll only know about them if you study the API documentation.

Finally, notice how you can even click the URL in the web browser, and a new tab opens.

This raw data is the API response formatted as JSON. There are 4 key-value pairs in the response: id (the API documentation tells us that every image has an id), url (this is the path to the image file stored on a content delivery network (CDN)), width (width of the image in pixels), and height (height of the image in pixels).

It's important to view how an API response is formatted before implementing it so that you know the names of the keys that you want to work with. In this example, we're only going to be using the url key.

Implement the API into the JavaScript program

Finally, we're at the stage of coding. I've embedded the exact HTML and JavaScript code that I used in this example below.

There's one extra step we'll have to do to use this API though. Since this API doesn't have CORS enabled, we're simply going to use a proxy server. In this example, we'll use a demo reverse proxy called CORS Anywhere. CORS Anywhere is an open-source project on GitHub (you can find the repository here). Essentially, it's a proxy server that adds CORS headers to the API request. To use it, click on the hyperlink I added above, and request temporary access to the proxy server.

When making the API call in JavaScript, all you have to do is prefix the API request URL with "cors-anywhere.herokuapp.com".

Time to start coding. First, I'm going to make a basic HTML document with a button element that will have a click event defined in the JavaScript program. I'll also add a div element that will contain the image of the cat. Finally, make sure to include your JavaScript file in the HTML body.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>

    <button id = 'img_generator'>Click for image of a cat!</button>

    <div id = 'img_container'>

    </div>

<script src = 'cat_api_call.js'></script>
</body>
</html>

Next, I'm going to make the API call in the JavaScript program (don't forget to prefix the API URL path with the CORS Anywhere URL), declare the image of the cat as a variable, and append the image to the HTML document using an event listener for the button.

// Define the url that we'll make the API call to (prefix with proxy server url)

const api_url = `https://cors-anywhere.herokuapp.com/https://api.thecatapi.com/v1/images/search`;

// Define relevant HTML elements

const img_generator = document.getElementById('img_generator');

const img_container = document.getElementById('img_container');

img_generator.addEventListener('click', getCat)

// Write an async function to call API

async function getCat() {

    // Wait for successful API call

    let response = await fetch(api_url);

    // Format JSON response to a JavaScript object

    let data = await response.json();

    // Define path to image by entering request body (data[0]) and retreiving value for the url key

    cat_img_url = data[0].url;

    // Add image to HTML document

    const img = document.createElement('img');
    img.src = `${cat_img_url}`;

    img_container.appendChild(img)
}

Test to see if everything works

Here is my beautifully designed webpage that allows users to click a button to get a picture of a cat.

And ta-da! It works!

Conclusion

I hope that this post helped clarify the concept of APIs, and also provided you with enough knowledge to start using APIs in your software.

Please comment down below if you have any lingering questions or suggestions for an article topic that I should cover in the future.

Also, please make sure to follow my newsletter to stay up to date on when I post new articles.