Lesson Weekend

In this lesson, we'll discuss the general concept of APIs, including what they are and how they work. This lesson is only meant to be a quick overview of APIs. We'll learn a lot more about how they work in future lessons.

Application Programming Interfaces

The term API stands for Application Programming Interface. In simple terms, APIs are a set of requirements that determine how one application may interface, or communicate, with another. APIs can be used with any programming language and are not specific to JavaScript.

For instance, when you're reading an article online, you might click a Share on Twitter button to publish the article to your Twitter feed. Following the requirements of the Twitter API, the news application communicates (or interfaces) with Twitter, publishing the article to your feed.

Requests and Responses

API calls involve making a request to a server and then waiting for a response from that server. In the example above, a user clicks the Share on Twitter button. Then the news application makes a request to Twitter's API with all the information needed to add a tweet of the article to the user's account. Finally, Twitter's API will respond with a message. In this kind of situation, the message usually just states whether the request was successful or not. If it is, the news application will inform the user. If not, the application will tell the user that there was an error and they should try again.

Header and Body

An API response has several parts including the header and the body. The header contains information such as the date, content type, any authorization information, and so on. Meanwhile, the body contains any messages from the API, a status code, plus data we've requested. In this section, we will mostly focus on the body of an API response.

Status Codes

All API responses come with a status code that lets us know the status of the API call. These codes are used in the browser as well and some will be familiar to you already. There are a lot of different status codes but there are only a few that we really need to be familiar with. Don't worry about trying to memorize these now. Just look them over so you have some general familiarity. You can always look up status codes as needed later.

  • 200: The API call was successful! This is also known as 200 OK.
  • 400: Bad request. We'd better check the API request and make sure it's correct.
  • 401: Unauthorized. We aren't authorized to access the resource, which might mean we haven't logged in correctly.
  • 403: Forbidden - we aren't allowed to access that content.
  • 404: Not found. The resource couldn't be found.
  • 500: Internal server error. Not our fault! Something is going on with the API. In general, if we get any 500 errors, the server is having problems.

For a full list of status codes, see Wikipedia's List of HTTP status codes.

API Calls are Asynchronous

The entire process of making an API call is asynchronous. Even though the user clicks a button now, they won't get a result back until later even if the call only takes a fraction of a second to process. It should be clear why API calls need to be asynchronous. It takes time to make a request and receive a response - and we don't want the user's browser to freeze up when that happens. That also means that the code itself is asynchronous as well so we need to handle it with special code to ensure that we don't handle API requests until after they are complete.

GET and POST requests

There are several different kinds of API requests. The most common are GET and POST requests. A GET request gets information. For instance, if we wanted to display all tweets mentioning the @Epicodus Twitter account, we could send the Twitter API a request asking for this information. The Twitter API will respond with a list of tweets mentioning @Epicodus.

In our first example earlier, the news application will make a POST request because information needs to be added to Twitter's server. The news application isn't asking to receive some information - it's asking for something to be changed.

We will be focused on making GET requests this week. Only GET requests will be required for this section's independent project. If you will be continuing on to a backend language such as Ruby or C#, you will be learning a lot more about different kinds of requests then.

Before we actually start writing JavaScript code to write API calls, we'll do the following:

  • Get an API key for the Open Weather Map API and explore API documentation
  • Download Postman, a tool for making API calls, and learn the basics of making a call
  • Practice parsing the JSON body of an API call

Only then will we be ready to start making API calls in our JavaScript code.

Lesson 3 of 26
Last updated October 12, 2021