5 Minute Intro to REST APIs

Learn the basics of APIs and what makes an API "RESTful"

So what is an API (Application Programming Interface)?

An API is a set of rules that allow one piece of software to talk to another.

It's pretty simple from a high-level — two applications interfacing (or “talking”) with each other via programs. APIs also make our lives easier by abstracting away complex code and replacing it with simpler, more straightforward code.

For example, think about what happens when you open a music streaming app and play a song.

There's probably some code that runs when you hit play that looks something like this:

That play() function is an API method that abstracts away things like:

  • The code needed to retrieve the audio file from the internet or your device

  • The code needed to send audio data to your device

As developers, we don't need to know or care about the lower-level code when we call the play() method, and that's fine! APIs are here to make our lives easier.


How do APIs work?#

In JavaScript, APIs are usually based on objects. In the example above, the mediaPlayer object is the entry point for the API, and play() is the API method.

Let's take a look at a more common example you've probably encountered before. If you've ever written JavaScript like this:

then congrats, you've used the DOM (Document Object Model) API!

Here, the document object is being used as the entry point for the DOM API, and querySelector() is the API method.

Note that these APIs aren't part of the JavaScript language, but rather they're built on top of JavaScript to give developers a convenient set of tools out of the box.


Two Types of APIs#

In the web development world, APIs generally fall into two categories:

  1. Browser APIs

    Browser APIs (like the DOM API) are built into your web browser and expose data from the browser and surrounding computer environment that developers can easily leverage.

  2. Third-party APIs

    On the other hand, third-party APIs (like the Twitter API or the Spotify API) are not built into the browser by default, and you have to retrieve their information from somewhere on the web.

Usually, when people talk about third-party APIs like the Spotify API or the GitHub API, they’re talking about REST APIs.


Regular APIs vs. REST APIs#

So if an API is a set of rules that allow one piece of software to talk to another, then REST (Representational State Transfer) is a standard set of rules that developers follow to create an API.

REST is a set of rules that determine what an API looks like.

Six conditions that need to be met for an API to be considered RESTful:

  1. Client-Server

  2. Stateless

  3. Cacheable

  4. Uniform Interface

  5. Layered

  6. Code-on-demand

I think you’d be hard-pressed to find anyone who remembers the definition of each of these conditions off the top of their head, so the gist of it is this:

  • When an application makes an HTTP request to a URL hosted by a server, the server should return a response with some data.

  • All requests should be independent of each other. It should be possible to make two or more HTTP requests in any order, with the same responses being received.

  • There should be a uniform interface between components so that information is transferred in a standard form (e.g. API methods)


RESTful Requests#

In a nutshell, you should be able to receive a piece of data (a.k.a. resource) when you access a predefined URL. Each of these URLs, also known as “endpoints", are part of what is called a request, and the data you receive from the request is called a response. The data provided by these responses are usually in the form of JSON (JavaScript Object Notation).

A RESTful request is composed of four parts:

  1. The endpoint URL

  2. The HTTP method

  3. The HTTP headers

  4. The body data

Let’s take a quick look at what each of these four parts are.

1. The endpoint#

The "endpoint" is the URL you request.

All REST APIs have a base URL (also known as the "root" endpoint). For example, the base URL of Spotify's API is https://api.spotify.com while the base URL of GitHub's API is https://api.github.com. Additionally, each endpoint in a REST API has a path that determines the resource being requested.

In the example endpoint above, https://api.spotify.com/v1 is the base URL, and /playlists/59ZbFPES4DQwEjBpWHzrtC is the path to a particular playlist.

Endpoints are just like any other URL you visit on the web, but instead of returning data for a website, they return resources (e.g. data like JSON)

2. The HTTP Method#

The HTTP method is the type of request you send to the server. There are five common types of HTTP methods: GET, POST, PUT, PATCH, and DELETE. They are used to perform four possible operations: Create, Read, Update, or Delete (CRUD).

  • GET: Retrieves or "reads" resources

  • POST: Creates resources

  • PUT / PATCH: Updates resources

  • DELETE: Deletes resources

When working with a REST API, the documentation should tell you which HTTP method to use with each request.

3. The HTTP Headers#

Headers are key-value pairs that are used to provide information to both the client and server. You can store things like authentication tokens, cookies, or other metadata in HTTP headers. 

For example, the header below tells the server to expect JSON content.

You can find a complete list of valid headers on MDN’s HTTP Headers Reference.


4. The Body Data
#

The "body" of a request contains any information you want to send to the server and is normally transmitted in the HTTP request's body by sending a single JSON-encoded data string.

This information is usually the data you'd like to create a new resource with (with a POST request) or the modified value of a resource you'd like to update (with a PUT or PATCH request). 

Note that since GET requests don't need any extra information from you to return existing resources, only POST, PUT, PATCH, or DELETE requests can have body data.


RESTful Responses#

Now that we know the parts of an HTTP request, let’s take a look at what is returned in an HTTP response: the status code and the body data.

Responses always include an HTTP status code in the response header. These status codes are numbers that indicate whether a request was successfully completed and range from the 100s to the 500s.

  • 100+: Informational response

  • 200+: Request has succeeded

  • 300+: Request has redirected to another URL

  • 400+: An error that originates from the client has occurred

  • 500+: An error that originates from the server has occurred

Similar to HTTP requests, responses usually return body data in the form of JSON.


REST APIs in the wild#

To wrap it all up, let’s take a look at a real-world example with the Spotify API.

Spotify’s Web API, which has a base URL of https://api.spotify.com/v1, has an endpoint that lets you get a playlist by its ID.

If you take a look at the docs, you'll see that the HTTP request’s endpoint (https://api.spotify.com/v1/playlists/{playlist_id}) requires a GET HTTP method and must have a valid Authorization header. It also requires a path parameter of the playlist’s ID.

So if you send a GET request to https://api.spotify.com/v1/playlists/59ZbFPES4DQwEjBpWHzrtC, the API's response will include body data that look like this:

This JSON includes things like the playlist’s number of followers, the URL of the cover image, the playlist’s name, and much more.

Next Steps#

Now that you have a solid understanding of REST APIs, try interacting with one yourself!

Coming Soon!#

Be sure to check out our new course being released soon, Build a Spotify Connected App, where we apply these concepts to build a real-world, full stack web app!


Sources#