Skip to content

What Even Is REST? (And Why Most APIs Calling Themselves RESTful Aren't)

10 min read4 views[Backend]
Cover image for "What Even Is REST? (And Why Most APIs Calling Themselves RESTful Aren't)"

What Even Is REST? (And Why Most APIs Calling Themselves RESTful Aren't)

I've been building APIs for a while now, and I still occasionally catch myself questioning whether something I'm designing is "properly REST" or just HTTP with JSON slapped on top. Turns out, that question matters more than most people think — and the answer is almost always "just HTTP with JSON slapped on top."

Let's actually dig into what REST is, where it came from, what it really demands, and why the gap between theory and practice is so wide.


Where REST Came From

REST — Representational State Transfer — wasn't invented by some startup trying to sell developer tools. It came out of Roy Fielding's 2000 PhD dissertation at UC Irvine. Fielding was one of the principal authors of the HTTP specification itself, so he wasn't theorizing from scratch — he was describing and formalizing the architectural style that made the web work the way it does.

The key insight in his dissertation is this: REST is an architectural style, not a protocol, not a standard, and definitely not a framework. It's a set of constraints. If your system satisfies those constraints, you get certain properties — scalability, visibility, reliability. If you ignore them, you lose those properties. It's that transactional.


The Six Constraints (The Actual Definition)

This is where most tutorials skip to "use GET for fetching and POST for creating" and call it a day. That's not REST. Here's what REST actually requires:

1. Client–Server

The client and server are separate concerns. The client handles the UI, the user state, the display logic. The server handles data storage, business logic, and resource management. Neither should care about the internals of the other.

This sounds obvious, but it has real implications: your API should not be designed around your frontend's convenience. It should model your domain. If you're building endpoints around what your React component needs to render, you've already violated the spirit of this constraint.

2. Statelessness

Every request from the client to the server must contain all the information needed to process that request. The server stores no session state between requests.

This is the one people understand intellectually but fight in practice. Session-based auth directly violates this. JWT tokens in the Authorization header satisfy it. When you say "but the server needs to remember who I am," the REST answer is: "then send that information with every request."

The payoff is huge — stateless servers are trivially scalable. You can spin up ten instances and any one of them can handle any request. No sticky sessions, no shared session stores.

3. Cacheability

Responses must label themselves as cacheable or non-cacheable. If a response is cacheable, the client (or an intermediate proxy) is allowed to reuse that response for equivalent requests.

HTTP already has the machinery for this — Cache-Control, ETag, Last-Modified, Expires. A RESTful API should be using these headers thoughtfully, not just ignoring them because "our data changes a lot." Even if something changes frequently, saying so explicitly (Cache-Control: no-cache) is different from just not thinking about it.

4. Uniform Interface

This is the defining constraint of REST, and it's actually four sub-constraints bundled together:

a) Resource identification in requests — Resources are identified by URIs. /users/42 identifies a specific user. The URI names the resource; the representation (JSON, XML, HTML) is separate from the resource itself.

b) Manipulation of resources through representations — When a client holds a representation of a resource (say, a JSON object for a user), it has enough information to modify or delete that resource. The server doesn't need to explain how.

c) Self-descriptive messages — Each message includes enough information to describe how to process it. Content-Type: application/json tells the receiver how to parse the body. HTTP methods tell the receiver what action is intended.

d) HATEOAS — Hypermedia as the Engine of Application State. This is the one almost nobody implements, and it's arguably the most important one. We'll get to it.

5. Layered System

The client can't tell whether it's talking directly to the server or through a chain of intermediaries — load balancers, caches, gateways, auth proxies. The API should behave identically regardless.

In practice this means: don't put logic in your responses that assumes the client has a direct connection to your application server. Don't leak internal IP addresses. Don't assume the caller can reach your database network.

6. Code on Demand (Optional)

Servers can extend client functionality by sending executable code — JavaScript being the obvious example. This one is explicitly marked optional in Fielding's dissertation, so it rarely comes up in API design discussions.


HATEOAS: The Constraint Everyone Ignores

Hypermedia as the Engine of Application State. Even the name sounds like it's trying to be difficult.

Here's what it actually means: the server drives the client's navigation through the application by embedding links in responses. The client doesn't need to know the URL structure upfront — it discovers what it can do from what the server returns.

A HATEOAS response looks something like this:

{
  "id": 42,
  "username": "tirok",
  "email": "dev@tirok.ir",
  "_links": {
    "self": { "href": "/users/42" },
    "posts": { "href": "/users/42/posts" },
    "edit": { "href": "/users/42", "method": "PUT" },
    "delete": { "href": "/users/42", "method": "DELETE" }
  }
}

The client follows links instead of constructing URLs. When the server moves a resource or changes its structure, clients that follow links adapt without breaking. The API becomes self-documenting in a live, machine-readable way.

This is how the web itself works. HTML pages link to other pages. You don't need to know the URL of the next page before you load the first one. HATEOAS applies that same principle to APIs.

Why does nobody implement it? A few reasons:

  • It's genuinely more work to build.
  • Most API consumers are purpose-built clients (mobile apps, SPAs) that already have the URL structure hardcoded anyway — the discovery mechanism feels redundant.
  • API documentation tools like Swagger/OpenAPI became a shortcut for the "discoverability" problem, even though they're a build-time document, not a runtime mechanism.

Fielding himself has written that if you're not doing HATEOAS, you're not doing REST. He's said this bluntly, in public, multiple times. Most of the industry has politely nodded and kept building JSON-over-HTTP anyway.


What We Actually Build: HTTP APIs

Let's be honest about what most "REST APIs" actually are. They're HTTP APIs with these conventions:

  • JSON bodies
  • HTTP methods used semantically (GET = read, POST = create, PUT/PATCH = update, DELETE = remove)
  • Resource-oriented URLs (/users, /users/42, /users/42/posts)
  • Stateless requests (usually — until you need sessions for something)
  • HTTP status codes used meaningfully (200, 201, 404, 422, 500)

This is a perfectly good pattern. It's predictable, widely understood, and plays nicely with HTTP infrastructure. It's just not REST in the academic sense. Fielding calls it "RPC with pretty URLs." That's a bit harsh, but he's not entirely wrong.

The term "RESTful" has drifted so far from the original meaning that it's essentially a synonym for "HTTP API with JSON." That's worth knowing, not to be pedantic, but because it matters when you're making design decisions and someone argues "but that's not RESTful."


HTTP Methods: The Part Most APIs Actually Get Right

If there's one part of REST that the industry absorbed correctly, it's the semantics of HTTP methods. Here's the practical breakdown:

GET    /users        → list all users
GET    /users/42     → get user with ID 42
POST   /users        → create a new user
PUT    /users/42     → replace user 42 entirely
PATCH  /users/42     → partially update user 42
DELETE /users/42     → delete user 42

Idempotency is worth calling out explicitly: GET, PUT, DELETE, and PATCH should all be idempotent — calling them ten times should produce the same result as calling them once. POST is not idempotent — sending the same POST twice creates two resources.

This matters for retry logic. If a network request times out, you don't know if the server processed it. For idempotent methods, retrying is safe. For POST, you need something like idempotency keys (a unique request ID the server deduplicates on) if you want safe retries.

# Django DRF example — proper method semantics
class UserViewSet(ViewSet):
    def list(self, request):        # GET /users
        ...
    def retrieve(self, request, pk): # GET /users/{pk}
        ...
    def create(self, request):       # POST /users
        ...
    def update(self, request, pk):   # PUT /users/{pk}
        ...
    def partial_update(self, request, pk): # PATCH /users/{pk}
        ...
    def destroy(self, request, pk):  # DELETE /users/{pk}
        ...

DRF's ViewSet enforces this structure pretty naturally, which is one of the things I actually like about it.


Status Codes: Where Most APIs Fall Apart

HTTP status codes are part of the uniform interface. Using them wrong breaks the self-descriptive message constraint. Here are the mistakes I see constantly:

Returning 200 for everything, including errors:

HTTP 200 OK
{ "success": false, "error": "User not found" }

This is the worst pattern. It makes the HTTP layer meaningless. Caches, load balancers, monitoring tools, and clients all look at status codes. When you bury errors in a 200, you're fighting the infrastructure.

Using 400 for everything that isn't a 500:

400 → client error (malformed request, validation failure)
401 → not authenticated
403 → authenticated but not authorized
404 → resource doesn't exist
409 → conflict (duplicate resource, state violation)
422 → request was well-formed but semantically invalid
429 → rate limited

The difference between 401 and 403 matters. The difference between 400 and 422 matters. When a client gets 401, it should try to re-authenticate. When it gets 403, re-authenticating won't help. These aren't stylistic choices — they're semantic signals that the entire HTTP ecosystem understands.


URL Design: The Things That Bite You Later

A few things I've learned the hard way:

Nouns, not verbs:

❌ GET /getUser/42
❌ POST /createUser
✅ GET /users/42
✅ POST /users

The HTTP method is the verb. The URL is the noun. When you put verbs in URLs, you've reinvented RPC.

Nesting: how deep is too deep?

/users/42/posts/7/comments/3/likes

This is technically valid but practically painful. If a comment's likes can be accessed independently, consider a flatter structure with query parameters for filtering. I try to never go more than two levels deep (/resource/{id}/sub-resource) without a good reason.

Versioning:

/v1/users
/v2/users

versus header-based:

Accept: application/vnd.myapi.v2+json

URI versioning is blunt but visible and cache-friendly. Header versioning is "more REST" (the uniform interface constraint argues the resource shouldn't change URL just because its representation changes) but harder to work with in practice. I use URI versioning. I've never regretted it.


So Should You Care About "True REST"?

Honestly? Depends on what you're building.

If you're building a public API that you expect third-party clients to integrate with over years, HATEOAS becomes more compelling — your clients can adapt to changes without breaking. If you're building an internal API consumed by your own frontend, the strict constraints matter less. You control both sides.

What you should care about, regardless of REST purity:

  • Stateless requests where possible — your future scalability depends on it
  • Meaningful HTTP status codes — your infrastructure and clients depend on it
  • Idempotency for the right methods — your retry logic depends on it
  • Resource-oriented URLs — your API's long-term maintainability depends on it

The REST constraints aren't arbitrary academic formalism. Each one solves a real problem the web encountered at scale. You don't have to adopt all of them religiously, but it's worth knowing why they exist before you decide to skip one.

That way, when you do skip one, it's a deliberate tradeoff — not an accident.

# Comments (0)

No comments yet. Be the first.

0/1000