REST vs. RESTful: The Difference and Why the Difference Doesn’t Matter

REST API is one of the most popular APIs in the web development community. Most teams reach for it before anything else, and most public web services you touch today describe themselves as REST or RESTful.

So what’s the difference between a REST API and a RESTful API? Is there a difference at all? It sounds like the kind of academic question that belongs on Reddit. Then you find yourself in a design session, and the person across the table starts raising their voice.

Here’s the short answer. REST stands for Representational State Transfer, an architectural pattern for building web services. A RESTful service is one that implements that pattern. REST is the noun; RESTful is the adjective. So when people argue about “REST vs. RESTful,” they’re really arguing about how closely a service follows the pattern, not about two competing technologies.

The long answer starts with “sort of” and “it depends,” and continues with the fuller definitions below.

What Is REST?

Let’s start with what REST is and is not. For a lot of developers, REST means a server that exchanges JSON documents with a client over HTTP. That’s not a complete definition, and it isn’t always true either. The REST specification doesn’t require HTTP or JSON. It doesn’t even mention JSON or XML.

The Origins of REST

Roy Fielding introduced the REST architectural pattern in a dissertation he wrote in 2000.

The document outlines a method for facilitating the exchange of application data between clients and servers. A key feature is that the client isn’t required to possess any prior knowledge of the application. You can find a detailed explanation of this concept in chapter five of the paper. Although the entire dissertation delves into the intricacies and rationales behind REST, this particular chapter serves as the definitive guide to the architectural pattern.

Fielding doesn’t hand you a checklist of requirements. Instead, he defines REST in terms of constraints and architectural elements.

The Six REST Architectural Constraints

Here is a summary of the constraints. There are six of them, and a service has to satisfy the first five to be considered RESTful. The sixth is optional.

• Client-server – REST applications have a server that manages application data and state. The server communicates with a client that handles the user interactions. A clear separation of concerns divides the two components. This means you can update and improve them on independent tracks.
• Stateless – servers don’t maintain any client state. Clients manage their application state. Their requests to servers contain all the information required to process them.
• Cacheable – servers must mark their responses as cacheable or not. So infrastructure and clients can cache them when possible to improve performance. They can dispose of non-cacheable information, so no client uses stale data.
• Uniform interface – this constraint is REST’s most well known feature or rule, depending on who you ask. Fielding says “The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.” REST services provide data as resources, with a consistent namespace. We’ll cover this in detail below.
• Layered system – components in the system cannot “see” beyond their layer. So you can easily add load-balancers and proxies to improve security or performance.
• Code on demand (optional) – servers can extend a client by sending executable code, such as JavaScript, for it to run. This is the one constraint Fielding marks as optional, which is why most summaries you’ll see online list only five.

A RESTful service is more than a web server that exchanges JSON, or any other, documents. These constraints work together to create a very specific type of application.

The Uniform Interface, in Detail

Fielding calls the uniform interface the feature that sets REST apart from every other network style, so it’s worth unpacking. It breaks down into four sub-constraints.

• Identification of resources – every resource has a stable identifier, usually a URI.
• Manipulation through representations – a client changes a resource by sending a representation of the new state, not by calling a method on the server.
• Self-descriptive messages – each message carries enough information to describe how to process it, for example its media type.
• Hypermedia as the engine of application state (HATEOAS) – responses include links that tell the client what it can do next, so the client discovers the API as it goes.

That last one, HATEOAS, is where most APIs fall short. We’ll come back to it when we get to the Richardson Maturity Model.

How the Constraints Work Together

First, the client-server, layered systems and stateless constraints combine to form an application with solid boundaries and clear separations between concerns. Upon request, data is transmitted from the server to the client, where it is displayed or manipulated. If any changes in state occur, the client sends the modified data back to the server for storage. Fielding makes a distinct comparison between REST and architectures that use distributed objects to shield data from other components. In REST, both the client and server share knowledge about data and its state. The architecture doesn’t conceal data, it only hides implementations.

The cacheable and uniform interface constraints go one step further. Application data is available to clients through a clear and consistent interface, and cached when possible.

So that’s the technical definition of REST. What does it look like in the real world?

What Is a RESTful API?

A RESTful API is a web API that actually follows the REST constraints above. That’s the whole definition. “RESTful” just describes a service that lives up to the pattern that “REST” names.

This is why the popular phrasing holds up in practice: every RESTful API is a REST API, but not every API people call REST is truly RESTful. Plenty of services advertise themselves as REST while quietly ignoring statelessness, HTTP verbs, or hypermedia. They’re HTTP APIs wearing a REST label. Whether that gap matters is the question we get to at the end.

RPC Over HTTP vs. RESTful

Often when someone says that a service “isn’t REST,” they’re looking at the URIs or how the service uses HTTP verbs. They’re referring to REST’s presentation of data as a uniform set of resources.

This distinction is sometimes framed as a difference between remote procedure calls (RPC) and REST. Imagine a web service for listing, adding, and removing items from an e-commerce inventory.

In one version, there’s a single URL that we query with HTTP GETs or POSTs. You interact with the service by POSTing a document, setting the contents to reflect what you want to do.

Add new items with a POST and a NewItem:

Query for items with a POST and an ItemRequest:

Some implementations accept a request for a new item with a GET, too.

We also change or delete items with a POST and an ItemDelete or ItemUpdate.

This isn’t REST. We’re not exchanging the state of resources. We’re calling a function with arguments that happen to sit in a JSON document or in URL parameters.

A RESTful service has a URI for each item in the inventory.

So adding a new item would look like the example above.

But the similarities end there. Retrieving an item is always a GET:

Deleting is a DELETE:

Modifying an item is a PUT:

The difference is important. In REST, operations use distinct HTTP actions. These verbs correspond directly to the activity on the data. GET, POST, PUT, DELETE and PATCH all have specific contracts. Most well-designed REST APIs also return specific HTTP status codes, depending on the result of the request.

The critical point is that the URIs operate on the data, not on remote methods.

But there’s another reason the resource model is essential.

REST vs. RESTful and the Richardson Maturity Model

Designing your URIs in alignment with resources and using HTTP verbs properly contributes to the predictability of your API. When developers understand how you’ve structured your resources, they can make informed guesses about the rest of the API. The focus is on understanding the data itself rather than the operations involved.

But even if you can’t make the API entirely predictable, you can document any REST service with hypertext. So each item returned by the inventory app would carry links for deleting, modifying, or setting the inventory level of the resource. Fielding says that before a service is RESTful, it must provide hypertext media as part of the API.

Many sites don’t meet this requirement but are still called REST. The fact is, many sites break the rules in one way or another. So many that Leonard Richardson created a model that breaks REST down into levels of compliance.

The levels run like this:

• 0 – exposing an API over HTTP with methods called with arguments (plain RPC over HTTP).
• 1 – exposing resources instead of methods.
• 2 – proper use of HTTP verbs.
• 3 – exposing hypertext with objects that make all or part of the API discoverable.

Richardson’s model is his own, and it doesn’t map directly onto Fielding’s spec. Since Fielding requires level three, he’d say that most apps aren’t REST anyway.

The point is that many services we colloquially call REST technically aren’t.

REST vs. RESTful: A Side-by-Side Comparison

When people draw a line between a plain “REST” API and a “RESTful” one, this is usually the line they have in mind. On the left is an HTTP API that borrows the REST label. On the right is a service that actually honors the constraints.

Notice that nothing in the left column is “wrong.” Plenty of solid, widely used services live there. The table describes a spectrum of compliance, not a pass-or-fail test.

REST vs. RESTful: Does It Matter?

So does the REST vs. RESTful comparison matter? Probably not as much as the design-session argument suggested. How well your architecture complies with an arbitrary standard isn’t as important as how well it suits your needs and can grow with your business.

The REST architectural pattern has real advantages. Fielding designed it for the web, and more than two decades later, most of the constraints he had in mind are still with us. In 2000 we didn’t have Android or the iPhone. IE5 held around half of the browser market. But Fielding recognized what online applications needed and how web clients would evolve from HTML display engines into complete applications. The tools we use today have grown to suit REST, not the other way around.

Richardson’s maturity model is a good guideline for designing your applications. You want to be at level two of the model, and to look at how level three might make your design better. Get there, and the label you put on it stops mattering.

Frequently Asked Questions

What is the difference between a REST API and a RESTful API?

Technically, none. REST is the architectural style; RESTful is the adjective for a service that follows it. In everyday use, people say “REST” for almost any HTTP API and “RESTful” for one that sticks closely to the constraints: resource URIs, correct HTTP verbs, statelessness, and hypermedia.

Is every REST API RESTful?

In casual usage, no. Many services labeled REST skip parts of the pattern, such as hypermedia or proper verb usage. Under Fielding’s definition they aren’t really REST at all, which is why the Richardson Maturity Model is handy for describing how close an API actually gets.

What are the six REST constraints?

Client-server, stateless, cacheable, uniform interface, layered system, and code on demand. The first five are required; code on demand is optional.

Does REST require JSON or HTTP?

No. The REST specification never mentions JSON, XML, or even HTTP. REST is a set of architectural constraints, not a protocol or a data format. HTTP and JSON are simply the most common way people implement it.

What is HATEOAS?

HATEOAS, or hypermedia as the engine of application state, is the part of the uniform interface that says responses should include links to the actions a client can take next. It’s what makes a service discoverable, and it’s the constraint most APIs ignore.

Is a REST API stateless?

Yes. Statelessness is a core constraint. The server keeps no client session between requests, so each request must carry everything needed to process it. The client owns its own application state.