📣 This post originally appeared as What is a REST API? on The Bearer Blog.
When working with APIs you may come across the term REST or RESTful. REST stands for Representational State Transfer. In essence, REST is a set of recommendations that an API can adhere to. This makes designing the API easier and using the API more predictable.
But how did we get to this point? Before REST, the main approach to designing web APIs was to use the Simple Object Access Protocol (SOAP). Where REST is an architecture style, SOAP is an officially standardized protocol maintained by the World Wide Web Consortium (W3C). Part of SOAP's allure early on, as well as it's eventual fall from popularity, was the strict and verbose nature of the standard. SOAP is tied to XML, includes security and authorization features, and works over a variety of protocols like HTTP and STMP. While most of these can be benefits to some organizations, the complexity that comes with the standard makes implementation more difficult.
REST was created to combat many of the problems of SOAP. Originally defined by Roy Fielding in 2000, REST has become one of the most popular ways to develop web services today. Where SOAP is a strict standard, Fielding's REST is an architecture style made up of six guiding constraints. It's also not tied to XML, even though many early REST APIs used it. Most current implementations use JSON instead.
The six guiding constraints of REST
REST's approach to guidelines allows APIs to be more modular and layered. As Fielding puts it:
REST is optimized for the common case so that the constraints it applies to the Web architecture will also be optimized for the common case.
Developers can add the functionality they need, while still providing some uniformity. The constraints, in no particular order, are as follows:
- Client-server: The client and server act independently. There is a clear separation of concerns, and requests and responses are exchanged to communicate.
- Stateless: Each request is self-contained in that it includes any information needed for the server to understand the request. The client can hold session state, but the server doesn't store any context.
- Cache: Designed to encourage caching, REST expects responses to be labeled as cacheable or non-cacheable. This allows clients to reuse responses for future requests if needed.
- Uniform Interface: The core distinguishing feature of REST is its interface. Regardless of where a resource (data) comes from, it is accessible via a predictable and consistent interface.
- Layered System: Where SOAP was very much "all-in", REST allows for a more modular, layered approach to building an API. For example, the API entry points can be decoupled from the auth server and the data sources as needed.
- Code on Demand (optional): The only optional constraint is one rarely seen in web APIs. Code on Demand allows the API to send executable code as the response. While this may sound appealing in certain circumstances, it is impractical when considering the variety of languages that the API consumer may use. In modern application's this also opens the door for additional client-side security concerns.
While these are guiding principles and constraints, they are not a set standard. This allows for some interpretation, however, the community does offer solutions like OpenAPI to try and solve some of the variability that may arise. It also allows more choice for features like authentication.
How it all works
With some foundational knowledge out of the way, let's look at how clients and servers use REST to interact. A REST API exposes endpoints. These are unique endpoints that build upon a core, base path. For example:
A base path may look like:
https://api.example.com
Endpoints may then look like:
/users
/user
/organizations/:id/teams
/profile
Endpoints can be defined with fixed values, like /users above, or through more dynamic paths like /users/:id where :id is replaced with a specific user ID. Additionally, endpoints can accept query strings made up of properties and values that act as instructions for the endpoint. For example: /users?limit=10&order=ascending may request a list of 10 users in ascending order. Combined, a full resource path ends up looking something like:
https://api.example.com/users?limit=10&order=ascending
^^Base Path ^^ Endpoint ^^Query String
These endpoints are then combined with a set of HTTP request methods to define the action they can take. These line up with the Create, Read, Update, and Delete verbs of "CRUD" applications. The core HTTP methods that endpoints focus on are:
- GET: Retrieve/Read data.
- POST: Create new data.
- PUT/PATCH: Update data.
- DELETE: Delete existing data.
GET and DELETE can interact with the endpoint itself, but POST and PUT/PATCH are capable of sending data in the body of the request. This is often as stringified JSON or Form data. All requests can, and often, contain a set of headers such as Authorization, Content-Type, and more that act to describe the request.
Once the client sends the request to the server, through the endpoint, the API server processes the request, performs the required action, and sends a response back. This response is normally in the form of an HTTP status code and a JSON object.
Beyond standard REST
As Fielding puts it in his original thesis:
REST is not intended to capture all possible uses of the Web protocol standards.
RESTful web services are dominant, but certain use cases have led to APIs that require more than REST can offer. Streaming, real-time communication, and data-heavy applications have pushed for different types of APIs.
One of the largest in this space is Facebook's GraphQL. Designed as a unified query language for APIs, GraphQL aims to give API consumers only the data they need, rather than large payloads that may contain excess content.
So is REST going away? Not any time soon. Even with the emergence of new approaches and standards, most of your integrations will still be RESTful. REST is still a safe option if you are building a new API today, but it may be worth considering alternatives like GraphQL, Falcor, or gRPC.
Looking for a solution to make your interactions with REST APIs more reliable? We're building just that at Bearer. Try it out today, and connect with us @BearerSH
Latest comments (7)
Thanks👍🏼 my understanding of REST just got better
Will start this off with the explicit statement I am not ant-REST. :)
That said, I will respectfully disagree with you on your statement This makes designing the API easier and using the API more predictable.
While REST brings a lot of good with it, it is not a defined protocol but a set of ideas sitting atop HTTP. This can cause a ton of headaches, not the least of which is endless bikeshedding about things like entities, which verb to use (yes, GET is the accepted verb for retrieving data, but nothing forbids a POST), etc. Plus, doing operations under REST can be extremely confusing.
GRPC carries the benefit of being a defined protocol, leaving little room for confusion.
That said, I think the most promise right now is GraphQL because it allows you to expose data as needed, and the shape of the data can be defined by the caller, potentially saving a ton of data transfer and handling.
Thanks for the write-up!
I was going to reply to this before you made the update, but you’ve basically said the things I was going to say :). My comment about it being “easier” was more in comparison to the status quo when it was created. I’d pick graphql if I were building an api today. That said, it also leaves quite a few of the hard problems up to the implementer.
It would be nice if you explain this more.
Also, it might contrast with GraphQL's GET vs POST.
It might be related to this.
Please ELI5 about POST / PUT / PATCH best practices
Pacharapol Withayasakpunt ・ Mar 11 ・ 1 min read
👍Caching (both on certain platforms and in various data structures) could be it's own article, as it's a pretty broad subject.
Regarding GraphQL, it is POST only as the query/mutation needs to be sent stringified in the body. The GraphQL spec itself doesn't have any cache support built-in, though they do recommend this approach
// , Oooooohhh, yes, ReST.
I'm filing this away in the "Classic Programmin' Stuff" folder, because it has only gotten better and more relevant with age.
Would this whole bearer.sh/ thingy work with the likes of HashiCorp Vault Enterprise, which has to rely on a ****-ton of external APIs to do its whole Access Composition or Access Brokering bidness?
If you’re accessing it through http requests from node or ruby, yep it’ll work with it.