When REST Gets in Your Way: A Practical Case Against Blindly Following REST
REST is not a protocol. It's not a standard. It's not even a specification. It's a set of architectural constraints described in a PhD dissertation from 2000 — and somewhere along the way, the industry turned it into a religion.
I'm not here to tell you REST is bad. I'm here to tell you that following it blindly, without understanding why the constraints exist and when they hurt more than they help, is bad.
What REST Actually Is
Roy Fielding's dissertation describes six constraints: client-server separation, statelessness, cacheability, uniform interface, layered system, and code-on-demand (optional). That's it. No mention of GET /users/{id}. No mention of JSON. No mention of HTTP status codes as a semantic contract.
What most people call "REST" is actually HTTP + JSON + some URL naming opinions. That's not an insult — it's just important to be clear about what you're actually committing to.
The constraints that actually matter in practice, the ones Fielding cared about, are mostly about network scalability and decoupling evolution of clients from servers. They were designed for the open web, where you don't control your clients, where caching intermediaries matter, and where your API will be consumed by people you'll never talk to.
If that's not your situation, some of these constraints will just get in your way.
The Uniform Interface: Where It Goes Wrong
The "uniform interface" constraint is the one that causes the most trouble. Fielding's idea was that resource-oriented thinking, with standard verbs and self-descriptive messages, makes systems more interoperable and evolvable.
That's a good idea in theory. In practice, it pushes you toward modeling everything as a noun, which breaks down almost immediately when your domain is full of actions and processes.
Take a payment system:
POST /payments ✓ create a payment
GET /payments/{id} ✓ get a payment
POST /payments/{id}/void ← is this RESTful?
POST /payments/{id}/refund ← also this?
POST /payments/process-batch ← now what?
You end up either cramming actions into fake resources (/payment-voids), or just adding verbs to your URLs and pretending you don't feel bad about it. Most real APIs I've seen do the second thing. The ones that force the first approach are usually painful to work with.
The domain has verbs. Void, refund, approve, reject — these are not resources, they're state transitions. REST's insistence on resources doesn't map well to them.
RPC-style thinking (not necessarily RPC as a protocol) is often more honest here. When your domain is action-heavy, say so.
Statelessness: Technically Correct, Often Misapplied
The statelessness constraint says the server should not store session state between requests. Each request must carry all the information needed to process it.
This is a genuinely good idea for horizontal scaling. You can spin up instances without worrying about sticky sessions or shared session stores.
But notice how often people misread this as: "don't use a database." The constraint is about request processing, not about persistence. You're allowed to store things in a database. You're allowed to have state — it just shouldn't live in the application server's memory in a way that ties requests together.
The real problem is when statelessness becomes an excuse for bad API design. "We're stateless, so we can't do multi-step operations" — no, you can. You just handle them differently, usually with a resource that represents the in-progress operation.
# Instead of: POST /checkout/step1, POST /checkout/step2
# Do:
POST /checkout-sessions # creates a session resource
PATCH /checkout-sessions/{id} # updates it incrementally
POST /checkout-sessions/{id}/complete # finalizes it
That's still messy, but at least it's honest. The problem is when the domain genuinely needs a conversation — a sequence of dependent steps where the intermediate state is complex. REST handles this awkwardly no matter what you do.
Overfetching and Underfetching: REST's Built-in Inefficiency
This is probably the most practical pain point, especially in mobile and frontend development.
With resource-oriented endpoints, you fetch a resource and get what you get:
GET /users/42
{
"id": 42,
"name": "Alireza",
"email": "...",
"bio": "...",
"avatar_url": "...",
"created_at": "...",
"last_login": "...",
... 20 more fields
}
Your mobile app needs name and avatar_url. You just fetched everything else for no reason. That's overfetching.
Then you need their recent posts and their follower count. That's two more requests:
GET /users/42/posts
GET /users/42/followers/count
That's underfetching — the resource didn't give you what you needed in one shot.
The classic answer is to add query parameters:
GET /users/42?fields=name,avatar_url&include=post_count,follower_count
Which works, but now you're essentially building a query language on top of REST. At some point you should ask: is this still REST, or am I just doing poor-man's GraphQL?
GraphQL exists because this problem is real. It's not a hype-driven replacement for REST — it's a direct solution to overfetching and underfetching on complex, graph-shaped data. If your data is graph-shaped and your clients have diverse field requirements, GraphQL is probably the right tool. The fact that it abandons REST's uniform interface is a feature, not a bug.
HTTP Methods as a Semantic Contract Is a Trap
REST encourages mapping operations to HTTP methods: GET for reads, POST for creates, PUT/PATCH for updates, DELETE for deletes.
This is a reasonable convention. It becomes a trap when you treat it as a strict contract.
The idempotency problem:
PUT is supposed to be idempotent — sending the same request twice should produce the same result. But in practice, most PUT implementations aren't truly idempotent because they don't do a full replacement:
# This is a PATCH pretending to be a PUT
def update_user(user_id, data):
user = User.objects.get(id=user_id)
for key, value in data.items():
setattr(user, key, value)
user.save()
You're partially updating a resource and calling it PUT. The HTTP spec says PUT should replace the entire resource. Almost nobody does this, because it's impractical — you'd have to send every field every time.
The DELETE body problem:
Technically, DELETE requests can have a body, but many HTTP clients, proxies, and frameworks either ignore it or don't support it. If you need to delete with some context (soft delete with a reason, bulk delete with a list of IDs), you end up at:
POST /users/delete-batch
{
"ids": [1, 2, 3],
"reason": "GDPR request"
}
Which is... not RESTful. But it works, it's clear, and nobody on your team has to remember which framework drops DELETE bodies.
When REST Is Actually the Right Answer
After all of that — yes, REST is often the right answer. Here's when:
Public APIs you don't control clients for. REST over HTTP is universal. Every language has an HTTP client. HATEOAS (when actually implemented) lets clients discover capabilities without reading documentation. The uniform interface genuinely helps when you don't know who's consuming your API.
Simple CRUD services. If your domain really is create/read/update/delete on a few resource types, REST maps to it naturally. Don't add complexity where there isn't any.
When HTTP caching matters. If GET responses can be cached by CDNs, browsers, or proxies, you get a lot of infrastructure for free. This is Fielding's original point, and it's still valid.
When teams are distributed and conventions matter. REST's conventions (GET /resources, POST /resources, GET /resources/{id}) are widely understood. If you're building something multiple teams will touch, that shared vocabulary has real value.
The Alternatives Worth Knowing
gRPC: Protocol Buffers over HTTP/2. Strongly typed, fast, good for internal service-to-service communication. The contract is defined in .proto files — no ambiguity. The tradeoff is that it's harder to debug (binary protocol), not supported in browsers without a proxy, and the tooling is heavier.
service UserService {
rpc GetUser(GetUserRequest) returns (User);
rpc CreateUser(CreateUserRequest) returns (User);
}
GraphQL: Query language for APIs. Clients ask for exactly what they need. Good for complex, graph-shaped data with diverse clients. The tradeoff is caching is harder (everything goes to POST /graphql), the N+1 query problem is real and you have to handle it explicitly (DataLoader pattern), and the learning curve for the server implementation is steeper.
tRPC: If you're in a TypeScript monorepo, tRPC gives you end-to-end type safety with zero schema definition overhead. Not relevant if you're not in that ecosystem, but if you are, it's one of the few API tools that actually delivers on its promise.
The Real Lesson
REST is a tool, not a religion. Its constraints exist for specific reasons — network scalability, client-server decoupling, long-term evolvability. When those reasons apply to your situation, the constraints are worth following. When they don't, you're carrying unnecessary weight.
The mistake isn't using REST. The mistake is using REST because "that's how APIs work" without asking what you're actually trying to achieve.
Design your API around your domain and your clients. If that maps cleanly to REST, great. If it doesn't, don't pretend it does — pick something that fits, or bend the conventions consciously and document why.
The worst API I ever worked with was RESTful on paper and completely unintuitive in practice. The best ones I've used made it obvious what to do, whether they followed REST or not.
That's the actual goal.
# Comments (0)
No comments yet. Be the first.