What is a REST API?

With the proliferation of APIs and buzz words like REST API and Serverless and other such terms, many people do not understand what they mean, much less what they actually are.

My goal with this article is to leave you, the reader, with at least a basic understanding as to what a RESTful API is and where it came from (and yes, note that I just called it RESTful).

My day job as a Solutions Architect involves me talking to developers, enterprise application architects and such similar roles. It never ceases to astonish me how many people that you would think are experts in their field, simply do not understand basic concepts like what a REST API actually is.

Sure, they nod and pretend to understand. But when you ask them pointed questions about it, it becomes clear that they just know it’s an API (Application Programming Interface, which I bet if you asked them to define what that is, they would have difficulty as well).

What’s the difference between a REST API and a SOAP API? Or a GraphQL API? “A REST API returns JSON and a SOAP API returns XML, and…. what’s a GraphQL API exactly?”. That is a real answer I got from a senior developer at one of my customers who I had been working with on a project and who had been a software developer for more than 5 years. As a Solutions Architect, it’s your job to empower your customers and make them feel good about what they are doing, so it’s always hard to be in these situations where you just want to say “Are you fucking kidding me?”. But instead end up saying something more like “Yeah, that’s about right, the only thing I would add is….”

So, what is a RESTful API?

First of all, REST = REpresentational State Transfer.

In order to give you a bit of background, I’d like to take you back to the year 2000, when a man named Roy Fielding wrote a dissertation paper at the University of California, Irvine while working towards his doctorate of philosophy in Information and Computer Science. The name of the dissertation paper was called “Architectural Styles and the Design of Network-based Software Architectures”.

If you are curious, you can read his paper in the archives of the University of California, Irvine here: Roy Fieldings Dissertation Paper.

This is where the world first was introduced to the concept of what an API could look like, if applied to the basic concepts of a RESTful interface.

Roy Fielding is considered by most to be the Father of REST and travels the world giving talks about it and thinking about how to advance web based architectures based on the REST principles.

You can follow Roy Fielding on twitter: Roy Fieldings Twitter Handle

To summarize the key points of what the RESTful interface requires for it to be categorized as a REST API, the following constraints are necessary:

Client-Server Model

A REST API must utilize the client-server architecture.

To quote Fielding, “By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components. Perhaps most significant to the Web, however, is that the separation allows the components to evolve independently, thus supporting the Internet-scale requirement of multiple organizational domains.”.

I think Roy summed it up pretty concisely.


I would say that this is one of the most important constraints of a RESTful architecture.

A REST API must be stateless. This means that on top of the client-server model, an additional constraint is added, a client-stateless-server model. This means that the server must not have any ties or relationships with the client. Every incoming request must be treated as if the server has no idea who the request is coming from and everything needed in order to process the request and return a response is passed on the api call itself. This means that any session state of the application must remain entirely within the client and not the server.

Gone are the days when you can store an entire array of data on the server and tie it to the the client via session tokens and such. A truly RESTful API has no concept of session context and stores nothing of it on the server.

What benefits does this actually give us? Well, it gives us several key things:

  • Visibility
  • Reliability
  • Scalability

From the words of Fielding:

Visibility is improved because a monitoring system does not have to look beyond a single request datum in order to determine the full nature of the request.”

Reliability is improved because it eases the task of recovering from partial failures.”

Scalability is improved because not having to store state between requests allows the server component to quickly free resources, and further simplifies implementation because the server doesn’t have to manage resource usage across requests.”

Uniform Interface

This is another key component to a well designed RESTful architecture.

Let’s take for example, a RESTful application that manages users. This means that the application will need to be able to do the following operations:

  • Create users
  • Edit users
  • Delete users
  • Read users

Basic CRUD operations. Things can certainly get more complex when you want to layer in other functionality such as relationships between users and other modules in the application or RBAC (Role Based Action Control) functionality etc but for the sake of simplicity, let’s use this example.

A uniform interface could mean, one api endpoint for a resource, and based on the type of operation you are attempting to perform, it would be requested differently. It also utilizes HTTP METHODS for different operation types. For example, an HTTP METHOD type of GET would read where as an HTTP METHOD of POST would create, an HTTP METHOD of PUT would update and an HTTP METHOD of DELETE would delete.

Let’s say our application is called My Amazing Application. The website would be and let’s say that the API endpoints for My Amazing Application would be something like and so if we wanted to get a list of all users in My Amazing Application, according to RESTful principles, it would be an HTTP METHOD of GET and the full url would look like like this:

However, if I wanted to get a specific user, it would be:

Now, what if the application wanted to change some details of my user? Maybe the application needed to update my address or phone number. They would use the exact same url as in the previous example, because we are still referencing the same resource. So the url would still be the only difference now would be, the HTTP METHOD will be of type PUT and a payload would now be passed in the body with the details of what exactly needs to be changed.

What if we wanted to delete my user? Same thing, but with an HTTP METHOD of type DELETE.

Do you see? The resource is users, which remains constant. The difference is how I am working with it. I am essentially passing an additional parameter saying, of the users resource, I want to work the user named ethan. And by specifying the HTTP METHOD, I am telling the API what to do with my user e.g. update, read, delete etc

The concept of a Uniform Interface is critical to a well designed RESTful architecture.

Data Response Format

I often see apis where they are named and because it returns JSON, they say that it’s a REST API. When I hear/see things like that, it makes me want to pull my hair out of my head and just scream!

For the record, NOWHERE in the dissertation does it specify the words “JSON”. An API can be considered fully RESTful in architecture if the response format is JSON, XML, CSV or even plain text!! JSON happens to be the most popular because it is easiest to work with in the world of web due to the fact that the browser executes JavaScript and JSON literally stands for JavaScript Object Notation. And because RESTful architectures got popularized by web based applications, most REST APIs nowadays return data in JSON. But this is just a convenience/popularity thing. It has no bearing on whether the API is actually RESTful.

There is much, much more to what a RESTful API is, and if you are curious, I highly recommend that you read the dissertation paper that I linked to above. That is the ABC’s for building out a RESTful architecture.

But hopefully this gave you a basic understanding of the key concepts of what REST is and maybe what it is not.

Please feel free to shoot me any questions in the comments section below and share this post with anyone you feel like they should know what a REST API actually is 🙂

Facebook Comments

Leave a Comment