What Is REST? Principles Explained Simply (With Examples)

What You'll Learn

• What REST actually means
• The six principles of REST
• What makes an API "RESTful" vs just "an HTTP API"
• Why REST became the default style for web APIs

Why This Matters

"REST" is the most-used word in API design — and the most-misunderstood. Many APIs called "REST" are not actually RESTful. Knowing the real principles lets you read API docs critically, design better APIs, and understand why things are done the way they are.

Simple Explanation

REST stands for Representational State Transfer. It is a set of architectural principles for designing web APIs, originally described by Roy Fielding in his 2000 PhD dissertation. REST is not a protocol, not a standard, and not a tool — it is a style. An API can be "more RESTful" or "less RESTful" depending on how many principles it follows.

Real-World Analogy — A Library

Imagine a library where every book has a unique shelf address (URL). To read a book, you walk to its address (GET). To add a book, you place a new one on the shelf (POST). To replace a book, you swap it (PUT). To remove one, you take it off the shelf (DELETE). The library does not remember you between visits — each visit is independent, and you bring everything you need (your library card = authentication token).

That is REST in a nutshell: resources identified by URLs, standard methods to act on them, and no memory between requests.

The Six REST Principles

1. Client-Server Separation

The client and server are independent. The client does not know how the server stores data; the server does not know how the client displays it. They communicate only through requests and responses.

Why: Lets client and server evolve separately. The server can change its database without breaking clients.

2. Statelessness

Each request contains everything the server needs to understand it. The server does not store any state about the client between requests. If you need to be authenticated, you send your token with every request — the server does not remember you logged in earlier.

Why: Any server can handle any request. This makes REST APIs easy to scale (just add more servers behind a load balancer).

3. Cacheable

Responses must mark themselves as cacheable or non-cacheable. If cacheable, the client (or a CDN) can reuse the response for future requests without calling the server again.

Why: Caching reduces server load and speeds up responses. The Cache-Control header implements this.

4. Uniform Interface

All resources are identified by URLs. All operations use standard HTTP methods (GET, POST, PUT, PATCH, DELETE). All responses use standard status codes. This consistency is what makes REST learnable — once you know one REST API, you know most of the structure of every other.

Why: Reduces the learning curve for new APIs. Tools like Postman and OpenAPI work uniformly across REST APIs.

5. Layered System

The client cannot tell whether it is connected directly to the server or to an intermediary (a proxy, load balancer, CDN, or API gateway). Each layer only knows about the next layer.

Why: Lets you add caching, security, load balancing, or routing without changing clients.

6. Code on Demand (Optional)

The server can temporarily extend the client by sending executable code (e.g., JavaScript). This is the only optional constraint — most REST APIs do not use it.

Why: Allows limited client extension without permanent changes.

What Makes an API "RESTful"?

The "Maturity Model" — How RESTful Is Your API?

Leonard Richardson defined a 4-level maturity model for REST APIs:

1. Level 0 (POX): One endpoint, everything is POST with XML/JSON. (e.g., SOAP over HTTP)
2. Level 1 (Resources): Multiple endpoints, each a resource. But still uses POST for everything.
3. Level 2 (HTTP verbs): Uses proper HTTP methods and status codes. Most "REST APIs" live here.
4. Level 3 (HATEOAS): Responses include links to related actions, so the client can navigate the API dynamically. Rare in practice.

Most production APIs are at Level 2. Level 3 (HATEOAS — Hypermedia As The Engine Of Application State) is theoretically pure REST but adds complexity that most teams do not need.

Common Mistakes

1. Treating REST as a strict standard. It is a style. APIs make pragmatic trade-offs (e.g., returning 200 with an error body) that violate pure REST but work fine in practice.
2. Using verbs in URLs. /getUser, /createOrder are not RESTful. Use nouns and HTTP methods.
3. Storing session state on the server. This violates statelessness. Send credentials with every request.
4. Assuming REST requires HATEOAS. HATEOAS is part of the original REST definition, but very few real APIs implement it. Most are Level 2 and that is fine.
5. Confusing REST with HTTP. REST is an architectural style; HTTP is the protocol most REST APIs use. You could implement REST over other protocols, but in practice REST = HTTP.

Practical Exercise (5 minutes)

For each of these endpoints, decide: RESTful or not RESTful? If not, rewrite it.

1. POST /api/getUser?id=123
2. GET /api/users/123
3. POST /api/deletePost with body {"id": 456}
4. DELETE /api/posts/456
5. GET /api/listAllOrders

Answers: 1. Not RESTful — use GET /users/123. 2. RESTful. 3. Not RESTful — use DELETE /posts/456. 4. RESTful. 5. Not RESTful — use GET /orders.

Mini Challenge

Pick any public API (Twitter, GitHub, Stripe, Slack). Look at its endpoints. How many of the six REST principles does it follow? Where does it break them? Most real APIs are "RESTish" — pragmatic compromises around the pure style.

Key Takeaways