What is REST?

September 4, 2019    |    APIs    |    Basics

TLDR;

REST is an architectural design for communication via HTTP.^[1] RESTful APIs provide software engineers and web developers with HTTP locations to send, receive, and manipulate data.

Overview

If you want to be a better programmer or web developer, you will need to understand what REST APIs are and how they work. In this article, I’ll describe what an API is and then describe the fundamentals of the RESTful API architecture.

What is an API?

Before diving right into REST, you need to understand what an API is. API stands for Application Programming Interface. To unpack this a bit, an API is a collection of methods that you can use to programmatically interact with a computer. For example, just as a keyboard is one interface in which I interact with my computer, in programming terms, I would use code to interact with the computer. An API is a set of special codes or methods that can be used to interact with the computer.

“an API is a collection of methods that you can use to programmatically interact with a computer”

What are APIs for?

There are many types of APIs that serve different purposes. Javascript, the primary programming language for the web, has many APIs that you can use to do many things. [2] Here are some common uses of javascript APIs:

• Manipulating HTML documents – Javascript has an API to edit HTML documents. For example, ReactJS, a popular javascript framework, make managing the state of an HTML document much easier.
• Getting data from another source – There is a whole API for requesting data from other websites. Fetch is now the standard way to request data in javascript. We will dive deeper into this API next.

Example fetch in Javascript:

fetch('http://cdn.richardkeller.net/favorite_movies.json')
.then(() => res.json())
.then((data) => {
   // Do something with the data here.
})

Other javascript APIs

• Creating and manipulating graphics
• Creating/editing audio or video
• Getting device information
• Storing data locally

Hopefully, by now you have a basic understanding of APIs. Now we can explore REST APIs. REST APIs are the bread and butter of web development.

What is a REST API?

REST stands for Representational State Transfer. REST is not a thing, but an architecture style of how computers can communicate over the internet using the HTTP protocol.[1]

At the most basic level, a REST API is a process of requesting data and then waiting for a response. You can think of this as calling someone on the phone and waiting for them to pick up. This is fundamentally the request/response cycle of the HTTP protocol.

Key Term: Response – a response is the result of a request in HTTP. Typically a REST API responds with JSON.

We call an API RESTful when it adheres to a certain architectural style that is semantically logical. When speaking of semantics and REST, we will focus on basic CRUD operations that you would usually perform with REST APIs. These operations are Create, Read, Update, and Delete.

For example, let’s say you have a lot of baseball cards and you want to create a database for those cards. In terms of CRUD, the basic operations for this database would be:

1. Create a new card
2. Read a card
3. Update a card
4. Delete a card

When we describe these actions a RESTful API, we use a URL (path on a server) and a method. Here are the same actions translated into REST API endpoints:

1. POST – Create a new card – /api/cards/new
2. GET – Get a card – /api/card/<card_id>
3. PUT – Update a card – /api/card/<card_id>
4. DELETE – Delete a card – /api/card/<card_id>

These endpoints make it possible to interface with your data from anywhere on the internet. In the following section, I’ll clarify some of the terms noted above.

HTTP Verbs

It’s vitally important to understand the verbs of REST. Here are the verbs and their corresponding descriptions.

GET

GET is the most common verb. In the example above, we “get” the object that contains our favorite movies by requesting the JSON file.

POST

POST is a bit different. In POST you send data to the server to create a resource. Building on the movie example, you could create a REST function to add a new movie to the favorite movies file.

PUT

PUT is another verb in which data is sent to the server, but instead of creating a new item, PUT updates an item.

DELETE

DELETE is another HTTP verb. DELETE is used for deleting items of a resource.

PATCH

PATCH is probably the least used HTTP verb. PATCH data is sent to the server to do a partial update for an item in a resource.

OPTIONS

OPTIONS is an HTTP request type typically sent during cross-origin requests in javascript.

Conclusion

What makes a good REST API is not the content, but the consistency of its request paths and responses. Making great REST APIs is essential to being a good developer. The skill of creating great APIs takes a lot of time, trial, and error. Since REST is a style rather than a specification, it is helpful to use best practices and follow some guidelines for consistency. I recommend reading Microsofts REST API guidelines for further information on best practices. I hope this has given you a little bit better of an understanding of REST. Thanks for reading!

References

1. “Representational state transfer“.wikipedia.com. Retrieved 2019-09-04.
2. “Introduction to web APIs”. developer.mozilla.org. Retrieved 2019-09-04.”