I’ve been a web developer for 25 years, and I’ve used dozens of REST APIs. Yet, it wasn’t until I started researching for this post that I realized how much I’ve missed, despite all that experience. This post provides an overview of REST APIs with some recommendations regarding when to use them.

A REST API provides a public interface for a data set, with optional validation for data manipulation. This allows developers to do a wide range of things from displaying data to creating new data without actually having full access to the data set.

Let’s start by getting the API part out of the way. API stands for Application Programming Interface. If you’re not familiar with APIs in general I recommend you read up on them and then come back to this post. REST stands for Representational State Transfer. If you want the intricate details, Wikipedia has a great post about it.

Benefits of REST APIs

Simplicity

At its core, a REST API is very simple. It’s just HTTP requests, and data is returned. Those requests can be made by anything that makes regular HTTP requests, from a plain web browser like Firefox to a dedicated API tool like Postman.

Flexibility

A REST API can be built any way you want. You can name things how you want and set up permissions how you want. As long as it’s operating over HTTP, it’s a REST API.

Drawbacks of REST APIs

Lack of a Standard

Because REST APIs can be built any which way, as a developer, you have to learn about each one from scratch. If the documentation or support is poor, this can be very difficult, if not impossible.

More Work to Build

While there are some common practices, building a new REST API from scratch requires a fair amount of engineering planning. Because there’s no real standard for how it’s built on the backend, you have to think through data flows, permissions, etc.

Learning About New REST APIs

Every REST API is different, even though many seem similar. WordPress, Drupal, and Joomla are three different content management systems that have the concept of a blog post and a REST API to interact with posts, but they each have different Routes and accept different variables for various Request Types.

This means that the only way to know how a given REST API works is through documentation or reading the source code itself. In most cases, you won’t have access to the source code. This means that the value of a REST API depends heavily on its documentation. Even if it’s amazingly powerful and well-written, if there isn’t information available on how to use it, it’s completely useless.

REST API Tips

In researching for this post, I found a couple gems that changed the way I think about REST APIs, even though I’ve been using them for years.

Routes are URLs, while Endpoints are Functions that power the URLs.

I’ve always just kind of used those terms interchangeably, but now that I think about them in that light, I see how they’re completely different.

HTTP request types matter.

When asking a REST API for data, you use a GET request. When sending a payload, you use a POST request. When deleting data from the server, you send a DELETE request. This makes a lot of sense but is quite different from GraphQL.

Summary

A REST API can be exceptionally powerful, and if it’s well written and documented, relatively easy to use. The issue regarding the fact that they’re all different will never truly be solved, so if you’re looking for a longer term, more flexible solution, you might want to take a look at GraphQL.