REST API Design Principles

REST is the style almost every HTTP API claims to follow, and interviewers love poking at whether we actually understand it. In simple language — REST is a set of rules for exposing our data as resources that clients read and change using plain HTTP.

REST stands for Representational State Transfer. Scary name, simple idea: we have things (resources), the client asks for a copy of a thing (a representation), and it changes state by sending representations back.

The three ideas that matter

Resources

A resource is any “thing” our API talks about — a user, an order, a product. Each one gets its own URL, called a URI. Think of it like — every noun in our system gets an address.

Representations

We never hand over the actual database row. We hand over a representation of it, usually JSON. The same user resource could be sent as JSON, XML, or CSV — the resource is the concept, the representation is the format on the wire.

Statelessness

This is the big one. Every request carries everything the server needs to handle it. The server keeps no memory of previous requests — no “session” sitting in server RAM tying requests together.

Why do we care? Because a stateless server is easy to scale. Any of our 10 servers behind a load balancer can handle any request, since none of them holds special context. We’ll dig into this more below.

Resource naming — nouns, not verbs

The single most common mistake. URLs should name things (nouns), not actions (verbs). The HTTP method already says the action.

A few naming habits worth locking in:

• Use plural nouns — /users, not /user. A collection is many things; /users/5 is one item inside it.
• Nest for relationships — /users/5/orders reads as “orders belonging to user 5”. Don’t nest more than one or two levels deep, though; deep nesting gets ugly fast.
• Hyphens, lowercase — /order-items, not /orderItems or /Order_Items.
• No file extensions — /users/5, not /users/5.json. Let the Accept header pick the format.

Use HTTP methods the way they’re meant

The method is the verb. Each one has an agreed meaning — use it and clients (and caches, and proxies) instantly understand our intent.

POST /users HTTP/1.1
Content-Type: application/json

{ "name": "Manish", "email": "m@example.com" }

# Server responds:
# 201 Created
# Location: /users/5

Notice we POST to the collection (/users) to create, and the server tells us the new item’s URL in the Location header. That’s the RESTful handshake.

Statelessness in practice

Because the server remembers nothing, the client must send its identity on every request — typically a token in the Authorization header.

GET /users/5/orders HTTP/1.1
Authorization: Bearer eyJhbGci...

There’s no “I logged in three requests ago so you know who I am”. Each request stands on its own. The trade-off: slightly bigger requests, but massively easier scaling and failover.

HATEOAS (the part nobody fully does)

HATEOAS — Hypermedia As The Engine Of Application State — means our responses include links telling the client what it can do next, so it doesn’t hardcode URLs.

{
  "id": 5,
  "status": "pending",
  "_links": {
    "self":   { "href": "/orders/5" },
    "cancel": { "href": "/orders/5/cancel", "method": "POST" }
  }
}

In theory this is the top level of REST maturity. In practice, most “RESTful” APIs skip it — so know what it is, but don’t sweat that your API lacks it.

So what makes an API “RESTful”?

Boiling it down: resources with clean noun URLs, correct HTTP methods, stateless requests, and standard status codes. Hit those and you’re 95% of the way there — HATEOAS is the bonus round.

Interview soundbite

REST models our system as resources addressed by noun-based URLs, manipulated with standard HTTP methods, where every request is stateless — it carries all the context the server needs. Use plural nouns, let the method be the verb (DELETE /users/5, never POST /deleteUser), return proper status codes, and optionally add hypermedia links (HATEOAS) so clients discover actions instead of hardcoding them.