API

An API (Application Programming Interface) allows you to send and receive data from a server. This is helpful because it means you can focus on presenting information in a unique or useful manner, rather than developing the underlying data set.

For example, most weather apps get their weather forecast data from a weather API, rather than building weather stations themselves:

National Weather Service’s API

Many APIs will provide documentation on how to interact with the data.

Example data from the endpoint https://api.weather.gov/gridpoints/LWX/96,70/forecast

In a web context, APIs enable interaction between client-side and server-side components, as well as with external services. For example, when you use a social media site, your browser (the client) sends a request to the site’s server using its API. The server processes the request, and then the API sends the data back to your browser. This data is then presented to you in a readable format.

While most APIs require access via API keys (which are similar to passwords), or have complex methods of authentication, there are also quite a few APIs with no requirements at all. This is especially useful for beginners, as it means you can start exploring different APIs right away.

Types of APIs

REST API

REST (Representational State Transfer) is a common software architecture on the web. In REST, a client (a computer or phone) sends a request to a server to perform an action: GET (to retrieve data), POST (to create data), PUT (to update data), or DELETE (to remove data). The server, which holds resources (like HTML files, images, and videos), processes the request and sends back a response in a format that the client can understand, usually in XML or JSON format.

JSON (JavaScript Object Notation) is a common format for data sent over REST APIs. It is a lightweight format that is easy for humans to read and write and for machines to parse and generate. It will look familiar to you, because you’ve used JavaScript objects before:

In this example, the top is the code that you write while the bottom is the data sent back from the server.

Internal API

These are used within the organization that created them, primarily to improve products and services from within. They allow different teams or parts of a software system to communicate with each other.

Example: A large retail company might have an internal API for its inventory management system. This API allows various internal apps, like the point-of-sale system and the online shopping portal, to check inventory levels, update stock, and manage orders.

External API

An External API is made publicly available for developers outside of the organization that created it. It allows third-party developers (you) to create apps that can communicate with the provider’s service.

Example: The Google Maps API is a web service API that allows developers to embed Google Maps on webpages using HTTP requests. This API provides various functionalities like showing a map with markers, providing directions, and displaying traffic conditions.

Check out this example on Google’s website and JSFiddle. Note that companies that provide APIs in this manner change them from time to time, and you may need to update your projects when that happens.

Figuring out how to use the API

You likely started your search for an API by searching “xyz API”. This probably led you to a website or GitHub repository that would also provide written instructions on how to use the API and what kind of data is available.

If you didn’t arrive at such a place, do another search for “xyz API documentation” and you will find either the official docs, or blog posts/articles written about the API. In general if an API doesn’t have documentation, it’s probably a sign that it isn’t actively maintained.

Authentication

Most APIs require some form of authentication to ensure that only authorized users can access them. This is akin to having a key that allows you to access the API’s data and functionality. There are several methods of authentication, but here are a few common ones:

API Key: An API key is a unique identifier that you include in API requests to authenticate your access. When you sign up to use an API, the service often provides an API key that you must include in your requests.

OAuth: OAuth is a more complex form of authentication that allows you to access the API without exposing your credentials. It’s often used for APIs that access sensitive data or allow you to perform actions on behalf of a user.

However, we’re not going to worry about this step because it’s needlessly fussy for your first time using APIs. There are plenty of auth-less APIs out there to interact with.

Getting the data with JavaScript

Once you’ve figured out how to authenticate (or you don’t need to authenticate) with the API, you can start making requests to get the data you need. Here’s a basic example using JavaScript’s fetch function to make a GET request to an API:

The fetch function in JavaScript is used to make network requests to retrieve resources from a server, such as API endpoints. More information here, if you’re curious: https://developer.mozilla.org/en-US/docs/Web/API/fetch

Even simpler, here is the bare minimum for getting data from an API:

Once you get the data, it might be a lot to parse. I’d recommend throwing it into your code editor or a beautifier to make it easier to read. Then you can find the particular data points you want to work with. A lot of the time, it’s trial and error to get exactly what you want out of the dataset.

If it’s still too much data to read through, you may want to change your data query to only get the relevant info, or write more code in order to extract and store the data you need.

More Examples

User Data

A practical example. Here let’s grab some sample user data and use it to populate the page from the free API at JSONPlaceholder:

Here we get the first five users from the data set and make some divs with template literals to substitute in their actual data.

Citi Bike

Here’s a more complex example, pulling from the CitiBike API:

In this we dynamically grab real-time station data to show capacity of various stations.

This is an example of a deprecated or unmaintained API, use with caution. It could be yanked from the internet tomorrow, or in 10 years.