A Beginner's Guide to APIs: How to Integrate and Use Them

Do you want to pull in weather data for your users? Get them the latest sports scores for your app? Want to make a site that tells your user a random joke?

You could go about writing all those jokes yourself or copying and pasting them into a file for your site to read from. Or you could just start using API integration and give your code superpowers to automate the whole process.

When you learn how to use an API, you're able to use services that would otherwise take you a long time to code yourself. You can add a robust search to your site with Algolia's API or a complete eCommerce experience with a SaaS Snipcart.

In this article, we'll go through:

• What’s an API?

• How to do an API integration?

• How to make a simple app with an API?

• How to troubleshoot API issues?

• Best API integrations to get started with

• No-Code API integration platforms

I'm excited to get you up and running with APIs integration! Before making a demo app with an API, let’s learn...

What’s an API?

API stands for Application Programming Interface, so we'll start by learning what an interface is.

What’s an interface?

Every device we use has some kind of interface. Your microwave has numbers and a start button on it, while a light switch has an even more straightforward interface.

We use these interfaces to get the device to do what we want. We don't need to understand the underlying circuitry and science to heat a bean burrito. We only need to use the interface that's been exposed to us.

Compare the internal workings of a car engine to what we interface with.

The inner complexity is abstracted away, leaving the user with the most straightforward interface possible.

What’s the "application programming" in API

Now that we know what the Interface portion means, the Application Programming bit is easier to understand.

An API is how applications talk to each other.

All software that you can interact with through code has some form of an API, so you'll see the term pop up in many places.

When web developers talk about "hitting an API," they usually mean a web service that lets you send requests and receive data in return. We'll touch on these soon.

Whenever I'm wondering, "How do I get this code to do what I want?" I searched for the API documentation related to that code.

You might have looked at the documentation on JavaScript libraries like Lodash to figure out how you need to format your code. The documentation teaches you how to use the API for that library.

How do web APIs work?

Your web browser has plenty of APIs built into it that we can use! These are called Web APIs. Chrome, Firefox, Safari, etc., have them built-in to use them to add features to our sites.

Some APIs let you play audio files, let your app understand user speech, respond to video game controllers, and lots more! When you listen for a click or a keyboard press in JavaScript, you're using the Event web API to do it.

We'll mainly look at HTTP web APIs for the rest of this article since web developers are most often referring to them when talking about API.

These are APIs that sit between your code and some data sources or functionality on a server that you'd like to access. They most often use the REST API architectural style to conform to certain criteria when making HTTP requests.

The API generally does two things:

1. For one, it sets rules for interacting with it.

The "rules" are the API saying, "if you structure your request like this, I'll send you data that's structured like this." If you don't structure your request in a way the API is expecting, it won't know what you want, and you'll get an error in response.

1. The API also handles data transfer between the server and the code making the request. The API is a program that acts as a middleman between the web app and the server and database.

Once it receives a valid request, it will run a function (or multiple functions). This is the complexity that the API is abstracting for the user. Depending on what you ask for, it might return an image, some data, or just let you know that it successfully received your request.

Let's touch on some concepts that you should understand when working with HTTP APIs.

Endpoints

APIs provide you with an endpoint or a specific URL where the data or functions you want are exposed. For Unsplash's source API, you access images through their endpoint at [<https://source.unsplash.com/>](<https://source.unsplash.com/>), adding your query parameters after the end slash.

In a later section, we'll look at some API documentation that outlines this agreement.

Authentication

Some APIs require you to sign up for an account or obtain a unique key to access their information. It might be to secure data, prevent abuse of the service, or because they want to charge a fee for the data.

If you're changing data on your database through an API, you need authentication. You don't want to give anyone else the ability to edit or delete your files!

With authentication, you pass the API a secret key that identifies a specific user or application request. The server can then determine if you're able to access the data or not.

If an API requires authentication, the API's documentation will explain how that works.

HTTP Verbs

With each HTTP request created, there is always an 'HTTP Verb' that goes along with it. The most commons are GET, POST, PUT, and DELETE.

When websites request data from a server, that's typically a GET request. POST and PUT are used to change or add data and DELETE deletes a specific resource.

This article only looks at public APIs, which usually only allow GET requests. So while we won't be using the other verbs, it's important you know they exist. It's a must-have for many web apps.

When Building an App

In your time as a developer, you might work for a company creating an application. If you're working as a frontend developer, you'll be provided API endpoints by your backend developers, along with directions for how to make requests and what to expect in return.

If you're working as a backend developer, it's your job to design and implement the APIs that run functions and query the database. You'll want to provide your frontend developers with clear documentation on how the API works.

If you're full-stack or building your own app, you might need to handle both parts. Luckily if you're using services like Auth0 for identity management, the creation of the API is handled for you.

Working with JSON

Most HTTP APIs you use will take and receive data in the JSON (JavaScript Object Notation) format. It makes learning how to read and write this format a pretty essential skill. JSON keeps its data in key-value pairs. Let's look at the JSON we get back when we request data from the Star Wars API. If we request this URL:

<https://swapi.dev/api/people/5/>

We will receive this JSON response:

{
    "name": "Leia Organa",
    "height": "150",
    "mass": "49",
    "hair_color": "brown",
    "skin_color": "light",
    "eye_color": "brown",
    "birth_year": "19BBY",
    "gender": "female",
    "homeworld": "<http://swapi.dev/api/planets/2/>",
    "films": [
        "<http://swapi.dev/api/films/1/>",
        "<http://swapi.dev/api/films/2/>",
        "<http://swapi.dev/api/films/3/>",
        "<http://swapi.dev/api/films/6/>"
    ],
    "species": [],
    "vehicles": [
        "<http://swapi.dev/api/vehicles/30/>"
    ],
    "starships": [],
    "created": "2014-12-10T15:20:09.791000Z",
    "edited": "2014-12-20T21:17:50.315000Z",
    "url": "<http://swapi.dev/api/people/5/>"
}

You can see the key/value relationship here. The key "name" has a value of "Leia Organa". We can use this object in our JavaScript code to display the information we choose or even make follow-up API requests.

If we were to query for https://swapi.dev/api/people/6/, the keys (name, height, mass) would remain the same, but the values (Leia Organa, 150, 49) would change.

JSON is a lightweight format that can be used across JavaScript, Python, PHP, and any other language you might be using on the web.

How to make an API integration?

Now that we have a better understanding of what APIs are, let's look at the integration process of an actual API and make our first requests. We're going to start simple with a joke API.

First, head to this URL.

The entire documentation takes place in this README.md file.

Looking at the documentation, I can see that we're given three endpoints.

If we want to "grab a random joke," we are given two possible syntaxes for this. There's nothing inherently different about those two links; the API author gives you two ways to approach using the API.

With this API, you can visit the URL in your browser, and you'll see the response.

In return for our request, we receive a JSON payload with four properties: the id of this random joke, its type, the setup, and the punchline for the joke.

Note that more complicated APIs will describe exactly what you'll receive in return. If you want to see a more complex response, take a look at this Yelp API endpoint for a business.

Looking Under the Hood

One thing I like about this jokes API is that it's relatively simple and open source. It allows us to look at the code that's returning our jokes.

All of the jokes are stored in a JSON file here. When we make our GET request, index.js is what handles our request by calling the appropriate function. The functions are stored here in handler.js, and there's only a handful of functions.

I recommend taking a look through those three files, even if you don't fully understand what they're doing. You'll see that APIs don't need to be complicated. Here the 'database' is a single JSON file.

Using an API Tool - Postman

When we make API requests, it's not usually by typing them into a browser but through code. It can be time-consuming to code out API requests when you're just trying to test if an API works. Luckily there's a free program called Postman that you can download here.

Postman is a robust program that I won't get too deep into, but I want you to be comfortable with creating a GET request with it.

Download, install, and open Postman. The HTTP action verb defaults to GET, so you can leave that and paste https://official-joke-api.appspot.com/random_joke as the request URL.

Click Send to send your request, and you'll see your response in the bottom panel.

That's it! You get a whole lot of information easily accessible with Postman. You can see the status, 200 OK, the time the request took to finish, and a lot more if you navigate the different tabs.

Now hit this endpoint in Postman: https://official-joke-api.appspot.com/random_ten

We're now requesting an array of ten joke objects, so the response's shape has changed.

Notice that the response body now begins with square brackets, [ ] instead of curly brackets, { }.

Some APIs like the Unsplash API return an actual image for the response payload. Try this endpoint and see what you get: https://source.unsplash.com/random

Getting familiar with Postman will help as you continue to use APIs and someday create your own.

How to use API to make a Joke Web App

Now that we've made this request a couple of ways and see what it returns, let's use the jokes API to create a little app.

We want our app to have a "Get Joke" button that triggers an API request. When the response returns from the API, we can display the setup and punchline to the user. When the button is clicked again, it makes a new request and displays the new joke.

We don't need any libraries or plugins to do this. We'll be using regular JavaScript to make the request.

I've built a CodePen starter that has some CSS already set up. Click here to open the starter pen and click "Fork" at the bottom right to create a copy of it.

Here's the final version if you want to check out what we're making.

Adding HTML

We'll start by creating our HTML. We don't need much for this demo: just a button and two paragraph elements.

<button id="button" type='button'>Get Joke</button>
<p id="setup"></p>
<p id="punchline"></p>

Make sure you include the ids and type="button" as shown. The ids have some styling tied to them, and we're going to reference them later in our JavaScript. The type="button" tells the browser that this isn't a typical form submission button.

Your CodePen window should look something like this:

Adding JavaScript

Now we'll move into the JavaScript window and make that button operational. First, we're going to add a click listener to the document.

document.addEventListener("click", function (event) {
  // Checking if the button was clicked
  if (!event.target.matches("#button")) return;

  console.log("Button was clicked!");
});

Here we're listening for all clicks. If anything that isn't the button gets clicked, we'll return, and the console.log() won't run. But if the button is the target, then we'll see our message in the console. Click the "Console" button at the bottom left of the CodePen UI to see that output.

At this time, we know our button works. Let's make it request our joke. We'll delete the line with the console.log() and replace it with a fetch() command.

Fetch is a web API! It provides us an interface to make requests and fetch resources. It's built into modern browsers and makes requesting data much easier. Read more here.

document.addEventListener("click", function (event) {
  // Checking if the button was clicked
  if (!event.target.matches("#button")) return;

  fetch("<https://official-joke-api.appspot.com/random_joke>")
    .then((response) => response.json())
    .then((data) => console.log(data));
});

We've added three lines here, the fetch() and two instances of .then(). Let's look at each line one by one.

  fetch("<https://official-joke-api.appspot.com/random_joke>")

Here we're using the Fetch API to request our joke endpoint. Like with Postman, the GET verb is the default, so we don't need to specify that. fetch() will send this request, and when it resolves or completes, it will pass the response data to our first .then().

.then((response) => response.json())

The period in front of the then() function means we are chaining our fetch request. This line of code will only run after the fetch has been resolved. fetch() returns a Response object, but we just want a JavaScript object, so we run the response.json() command. The result of that gets passed to our next line of code.

.then((data) => console.log(data));

We're chaining again and logging out the JSON that resolves from above. Click the button and check your console. It should look something like this.

This is great; we're successfully fetching data from the API with JavaScript! Now we'll display the joke in our HTML elements.

We'll add a function to the bottom of our JavaScript called renderJoke. It'll take the object we get back from the endpoint and add each element's innerHTML.

function renderJoke(data) {
  const setup = document.getElementById("setup");
  const punchline = document.getElementById("punchline");
  setup.innerHTML = data.setup;
  punchline.innerHTML = data.punchline;
}

Now change the last line of our fetch() chain from this:

.then((data) => console.log(data));

To this:

.then((data) => renderJoke(data));

Instead of logging out the data, we're now passing it to our new function. Your JavaScript should look like this:

document.addEventListener("click", function (event) {
  // Checking if the button was clicked
  if (!event.target.matches("#button")) return;

  fetch("<https://official-joke-api.appspot.com/random_joke>")
    .then((response) => response.json())
    .then((data) => renderJoke(data));
});

function renderJoke(data) {
  const setup = document.getElementById("setup");
  const punchline = document.getElementById("punchline");
  setup.innerHTML = data.setup;
  punchline.innerHTML = data.punchline;
}

When you click the button, it should return a joke like this:

If you've got this working, congratulations! You're now making an API request with JavaScript, handling the response, and displaying the results in HTML! That's a huge accomplishment. 👏

Handling Errors

Sometimes API requests don't succeed, and we need our websites or apps to let the user know something didn't go as planned. It's a pretty bad user experience to click a button, and nothing happens. Let's simulate that by adding a typo to the API endpoint. I've changed my string to "<https://official-joke-api.appspot.com/random_jo>" to force an error.

Now click the joke button. It seems like nothing happens, but if you open your developer tools and check the console, you'll see that the API responded to our request with a 404. It is the API saying it couldn't find what you're requesting.

Let's add some code to let the user know when our API returns an error.

First let's add a new paragraph element to our HTML with id="error".

<button id="button" type='button'>Get Joke</button>
<p id="setup"></p>
<p id="punchline"></p>
<p id="error"></p>

We'll then create a renderError() function to add a message to that HTML element when we get an error.

function renderError() {
  const error = document.getElementById("error");
  error.innerHTML = "Whoops, something went wrong. Please try again later!";
}

Now we're going to add a special function to our fetch() chain that catches any errors.

fetch("<https://official-joke-api.appspot.com/random_jo>")
    .then((response) => response.json())
    .then((data) => renderJoke(data))
    .catch(() => renderError());

If the fetch request succeeds the .then() functions will be called in order and the .catch() function won't be called. But if the request fails, it'll skip the .then() functions and call the .catch() only.

Click the button; now the user is notified that the request failed.

Last, we need to clear out the error message if the user tries again and the request succeeds. Add this code to our renderJoke() function.

const error = document.getElementById("error");
  error.innerHTML = "";

Fix the API endpoint so that it's" <https://official-joke-api.appspot.com/random_joke>" once more.

We're all set! Here's the final app if you'd like to check it against your code.

Extra Credit

You could continue to build on this app and add some more features.

Like letting users select a category and then change that part of the API request. You could also have some way of hiding the punchline until the user has clicked another button or a couple of seconds have passed. You could even use the endpoint for ten jokes and give the user a handful of laughs without making additional requests.

I'd love to see what you come up with!

Troubleshooting APIs

Eventually, you'll run into some trouble with APIs, and you'll need to debug a problem in your code. Here are some tips on how to troubleshoot when the API isn't doing what you expect.

Check the Documentation

If you're using a publicly available API, there should be documentation to tell you how to structure your request. Make sure you're following the syntax described there. Compare their examples to what you have in your request to see what's different.

Check the Network Tab

If you're making your API requests in the browser, one of the best API troubleshooting tools is the Network tab. In Chrome, you can press Control + Shift + J in Windows or Command + Option + J on a Mac to open DevTools. Click the Network tab at the top. Now the Network tab will listen to every single request that the website makes.

Here's a request from the joke app we made earlier.

This shows us the URL we made our request to, our Method (or verb), and the status code we received in return. You can see what the API returned in the Preview and Response tabs.

If your status code isn't 200, read on.

Check the Status Code

You've seen "404 File Not Found" on a website when you clicked a dead link or typed something wrong. That 404 is a specific code that the server gives to your browser as feedback on its request.

Either in the network tab or Postman, you will always receive a status code from the API.

It's one of many HTTP status codes that help us understand how our requests are being received. The responses are grouped into hundreds:

• 1xx informational response – the request was received, continuing process

• 2xx successful – the request was successfully received, understood, and accepted

• 3xx redirection – further action needs to be taken in order to complete the request

• 4xx client error – the request contains bad syntax or cannot be fulfilled

Generally speaking, a response of 200 or anything in the 200's is a success.

Anything in the 400 's means the request failed, and the cause is probably our error. Check the list of HTTP status codes for the specific code you received. If it's a 400 you should check that your request is formatted correctly.

Anything in the 500 's means something went wrong on the server that handled your API request. The server might be down, or there might be a bug in the code. Try your request again after a little while.

CORS

When working with APIs, you're likely to someday run into what's known as a CORS (Cross-Origin Resource Sharing) error. You've got a CORS error if you check your console and see a message about "No 'Access-Control-Allow-Origin' header is present on the requested resource'.

Here's a good resource for learning about and fixing this error when you encounter it.

Issues with Promises

One thing we didn't get into in this article was the concept of Promises. When working with APIs, you begin to work with the concept of asynchronous programming. It's outside the scope of this article, but if you're having trouble working with the data that gets returned from your API requests, you might be running into an issue with Promises. Here's a great article to get you caught up.

Best API integrations to get started with

There are a ton of free APIs for you to use for whatever kind of project you'd like to make. Here's a full list of hundreds of APIs, but I'll outline a couple below with ideas on how you might get started.

Unsplash

Unsplash is a great resource for downloading completely free stock photographs, but did you know they have a public API too?

Check out Unsplash Source and think about how you can use this API to add beautiful images to your next project.

Pokemon API

The PokeAPI is a free API that doesn't require authentication to access. There are a few different endpoints available to you, which means you can ask for different kinds of data. You can query for specific Pokemon, moves, games, locations, and a lot more.

Here's a Catch Pokemon app example based on our Joke app from earlier to help you get started.

The Dog API

The Dog API returns random pictures of dogs! The best bit is you can ask for dogs in specific breeds, which gives you the chance to make a more complex web app.

If you'd like a basic concept, you could make something similar to the Pokemon app, but with another level of complexity. Take a look at some wireframes for this app idea.

This app shows a random picture of a dog but has a dropdown that lists all the breeds so the user can narrow the pool of images they receive.

First, your app could use this endpoint to receive all the breeds the API has: https://dog.ceo/api/breeds/list/all

Then you can include their selection in a request to this endpoint: https://dog.ceo/api/breed/hound/images, replacing hound with their choice.

Read the docs here to see what that will return. That should get you started!

No-Code API integration platforms

We aren't going to dig into these connector applications options much, but I want you to know these are available in case these best fit your needs.

Some services like Zapier or IFTTT provide an easy interface for people to connect different APIs to their ecosystem. They also reduce the need for API management.

This example from the Zapier homepage connects the Gmail, Dropbox, and Slack APIs. This would take a bit of time for you to code yourself, but Zapier creates an interface on top of these APIs, further abstracting the complexity!

You might be able to use "no-code" solutions like Zapier to wire up a few actions, but you're limited in what you can do. You sacrifice ease of use for flexibility. For this reason, it's good to know these tools exist and understand how to use web APIs yourself. Then you can choose the best solution for your digital transformation tasks.

Wrap Up

We touched on a lot in this article, so congrats for making it to the end.

We looked at the concepts of interfaces and how an API abstracts away complexity. We touched on web APIs and then dug deep into HTTP APIs. We used Postman to make requests and even created our Joke app! We explored a few more APIs you could play with and saw that sometimes no-code solutions could be the way to go.

I hope you learned a lot and feel more confident working with APIs in the future. While some APIs can be incredibly complex, the underlying concepts remain the same.