What REST really is (and what it isn’t)
One of the most common ways to implement dynamic web applications is by separating the client from the server. We usually write the clients using a frontend stack, which is basically HTML, CSS and some Javascript, and the backend using a server-side technology, these days Python and Typescript seem to be quite popular for this. The communication between Client and Server takes place via APIs exposed by the server-side application.
When building applications using this approach, it's very common to hear the term REST followed by API, REST is not the only way of building APIs but it's certainly the most popular and widely used. I've worked with probably thousands of engineers by now and a lot of them didn't have the foundational knowledge about REST to understand what they're doing and, moreover, doing it better. So, let's start.
REST, short for Representational State Transfer, is frequently described as an API style or a way of building web services. While not incorrect, this description is incomplete and often misleading. REST is not a framework, a protocol, or a specification to be implemented line by line. It is an architectural style defined by a set of constraints that guide how the different parts of a distributed systems communicate with each other.
REST was introduced by Roy Fielding in his doctoral dissertation as a way to describe an architecture for the World Wide Web. Understanding REST correctly requires stepping back from tools and libraries and focusing instead on the principles and technologies that the interactions between clients and servers.
A system can be called RESTful only if it adheres to those constraints, the most relevant are: stateless communication, a uniform interface, resource based modeling, and representation driven state transfer. We will dig deeper into those principles and constraints in future posts. For now, let's focus on what REST is not.
REST is not CRUD over HTTP
One of the most common misunderstandings is equating REST with CRUD operations exposed through HTTP endpoints. While many RESTful APIs support create, read, update, and delete operations, REST itself is not about data manipulation. It is about how state is transferred between systems.
For example, exposing an endpoint like /createUser that accepts a POST request is not RESTful, even if it uses HTTP correctly. The action is embedded in the URL, and the resource being manipulated is implicit rather than explicit. I've seen this mistake countless times in different jobs, working with different teams and, to be quite frank, in all the clients I worked with during my years as a consultant with BCG X.
A RESTful alternative to that would be:
POST /users
Here, the URL represents a resource, and the HTTP method expresses the action. This distinction might appear subtle at first, but it becomes critical as systems evolve and grow in complexity.
REST is not JSON over HTTP
Another widespread misconception is that REST requires JSON and HTTP. In reality, REST does not mandate any particular data format or transport protocol. JSON is simply the most popular representation format used today because it is lightweight and widely supported.
In reality, a RESTful system could use XML, HTML, plain text, or even binary formats. What matters is that resources are represented in a format that both client and server understand and that the representation can evolve independently from the underlying implementation. One interesting application of the REST principles is Hotwire, an implementation that uses RESTful patterns an sends HTML over the wire instead of JSON, saving time by removing the need for transforming the server response into something the browser can render.
Statelessness and its implications
One of the defining constraints of REST is statelessness. This means that the server does not store any contextual information about the client between requests. Each request must contain all the information necessary to process it.
This has important implications. Authentication information, pagination details, localization preferences, and content negotiation headers must be sent with every request. While this might seem inefficient at first, statelessness greatly improves scalability and reliability. Servers can be added or removed without affecting client interactions, and requests can be routed freely across infrastructure making it easy for systems to scale horizontally. This requires Engineers to deeply understand how HTTP requests and responses work.
Why understanding REST matters
Not understanding REST often leads to APIs that work at the beginning but become difficult to maintain. Clients end up tightly coupled to server implementations, workflows leak into client logic, and small changes cause widespread breakage.
When REST is applied thoughtfully, APIs become easier to understand, easier to evolve, and easier to integrate. The goal is not theoretical purity but building systems that can survive growth, change, and long term use.
This will be a series of posts about REST and APIs I've been working on for a while based on books I've read and experience in designing, leading, implementing and maintaining APIs at different levels.
If you like what you read or resonate with my opinions, please consider subscribing, it's free!