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.
The term API stands for Application Programming Interface. In simple terms, APIs are a set of requirements that determine how one application may communicate, or interface, with another. APIs can be used with any programming language and are not specific to JavaScript.
At this point, we're very familiar with Web APIs, which are a collection of APIs, each with tools that developers can use in their applications to interact with the browser window, the DOM, events, and other browser structures. These tools are made up of object types, properties, and methods that are built-in to our browser.
Let's consider another example of an API. 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.
While we won't be using the Twitter API, we'll be working with similar third-party APIs. A third-party API is provided by a company to use their data or services. Think of MapQuest, sites with free images like Unsplash, music sites like Spotify, or even the US government and NASA. There's a lot out there!
API calls involve making a request to a server and then waiting for a response from that server. In the Twitter API example, the request-response process goes like this:
This is unlike the process of using Web APIs, which are built into our browsers. With Web APIs, we simply need to know which object (or property) we're targeting, and make sure that we access it properly (like using the right syntax when we use it).
On the other hand, with third-party APIs we always need to make a request to a server for information and wait for a response.
An API response has several parts including the header and the body:
In this section, we will mostly focus on working with the body of an API response.
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.
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.
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 earlier Twitter API example when we posted the news article to our Twitter feed, the news application makes 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 in this section. Only GET requests will be required for this section's independent project. When you study a backend language such as Ruby or C#, you will learn about making other kinds of requests, like POST requests.
Before we actually start writing JavaScript code to write API calls, we'll do the following:
Only then will we be ready to start making API calls in our JavaScript code.