Your REST API Was Almost Never REST

The problem

Almost every web API has been called REST at some point.

Even when it does things like:

• POST /create-user
• POST /approve-order
• POST /cancel-subscription
• POST /generate-report

All over HTTP. All with JSON. All with status codes.

And that is where the confusion starts.

Many people treat “REST” as a synonym for:

• web API
• HTTP endpoint
• JSON going back and forth

But that erases an important difference.

One thing is using HTTP as transport.

Another thing is modeling an interface with resource-oriented semantics.

Mental model

Think about it like this:

most APIs the market calls REST are, in practice, HTTP+JSON with some useful conventions

That is not an insult.

It is just a more honest description.

The mistake is not failing to be “pure” REST.

The mistake is:

• using the label to sound sophisticated
• forcing bad modeling in the name of the label
• losing clarity about the kind of interface you actually exposed

Breaking the problem down

REST is not only HTTP verbs with pretty URLs

When someone talks seriously about REST, they are talking about an interface where:

• resources are central
• operation semantics stay consistent
• the HTTP protocol participates in the meaning
• the conversation stays relatively predictable for the consumer

In practice, that usually looks like:

• GET /orders/123
• PATCH /users/42
• DELETE /sessions/current

Here, the resource is clear.

An API full of explicit commands may still work very well.

But it is not necessarily playing the same game.

The market calls many things REST by convention, not precision

That happened because “REST API” became a short label for “normal HTTP API.”

That is understandable.

But it creates a bad side effect:

the team stops distinguishing between:

• a resource-oriented interface
• a command-oriented interface
• a hybrid interface

And when that distinction disappears, API design gets worse.

The problem is not impurity. It is confusion

A lot of REST discussion turns childish very quickly:

• one side wants theoretical purity
• the other side dismisses semantics altogether

Both sides miss the point.

You do not need to become a Richardson Maturity Model inspector to design a good API.

But you also should not call any collection of POST /doThing endpoints REST just to end the conversation.

Commands dressed up as resources usually create strange endpoints

This is a classic symptom.

When the domain is action-heavy, the team tries to force a resource model and ends up with things like:

• POST /orders/123/approve
• POST /orders/123/cancel
• POST /reports/generate

That is not automatically wrong.

But it is a sign that the real interface may be closer to command than to pure resource manipulation.

Understanding that helps the conversation become more honest.

A good API does not need to win a philosophical argument

It needs to be:

• clear
• predictable
• consistent
• evolvable

If REST conventions help with that, great.

If forcing REST makes the boundary less clear, it is better to admit the nature of the operation and design it more honestly.

Simple example

Imagine an order API.

Part of it is clearly resource-oriented:

• GET /orders/123
• GET /orders?status=paid
• PATCH /orders/123

But part of it is dominated by business actions:

• approve order
• capture payment
• resend invoice

If you try to pretend everything is only “resource update,” you may end up with awkward endpoints and weak contracts.

A pragmatic model may accept a controlled mix:

• resources where resource is the right abstraction
• explicit actions where command is the honest abstraction

The important thing is not winning on the label.

It is not confusing the consumer.

Common mistakes

• Assuming HTTP + JSON + status code already settles the whole REST conversation.
• Defending theoretical purity and making the API ergonomics worse.
• Forcing business commands into an artificial resource model.
• Using the REST label without thinking about contract consistency.
• Debating names too much and semantics too little.

How a senior thinks about it

Someone with more experience usually does not ask:

“Is this real REST?”

They ask something better:

“Is this interface clear about what is a resource, what is a command, and how the consumer should think about it?”

That question is much more useful.

Because it moves the conversation away from performance and into operations.

A mature interface does not need to sound pure in theory.

It needs to reduce ambiguity.

What the interviewer wants to see

In interviews, this topic measures conceptual clarity and pragmatism.

The evaluator wants to see whether you:

• understand that REST is more than HTTP transport
• do not fall into unnecessary purism
• can explain when resource makes sense and when action dominates the interface
• prioritize contract and clarity over label

A strong answer often sounds like this:

“I would say most APIs called REST in the market are really HTTP+JSON with REST conventions. That is not a problem by itself. The problem is not knowing whether I am modeling a resource or a command and ending up with an inconsistent interface. For me, the priority is contract clarity and semantics that are useful to the consumer.”

The opposite of a good API is not ‘not being pure REST’. It is being confusing.

When the team stops arguing about labels and starts arguing about semantics, the design gets much better.