REST Principles

What is REST?

REST (Representational State Transfer) is an architectural style for web APIs, defined by Roy Fielding in 2000. It's a set of conventions — not a protocol — for building predictable, HTTP-native interfaces.

Resource-based URLs

In REST, everything is a resource, identified by a noun (not a verb). The HTTP method supplies the action:

GET    /articles          # list
POST   /articles          # create
GET    /articles/42       # fetch one
PUT    /articles/42       # replace
DELETE /articles/42       # remove
GET    /articles/42/comments  # nested resource

Use plural nouns, lowercase, hyphenated. Never put verbs like /getArticle or /createUser in the path — the method already says what to do.

Statelessness

Each request must contain all the information the server needs to understand it. The server stores no session state between requests — authentication comes via a token in the header, not server memory. This makes REST services trivially scalable: any server can handle any request.

HATEOAS

HATEOAS (Hypermedia As The Engine Of Application State) means responses include links to related actions, like a web page does:

{
  "id": 42,
  "status": "unpaid",
  "_links": {
    "pay":    { "href": "/invoices/42/pay" },
    "cancel": { "href": "/invoices/42", "method": "DELETE" }
  }
}

The client follows links rather than hardcoding URLs. Few APIs implement full HATEOAS, but it's the ideal REST aims for.

Versioning

Plan for change. Common strategies: URL versioning (/v1/articles), header versioning (Accept: application/vnd.api+json;version=1), or query parameters. URL versioning is the simplest and most widely understood.

REST is about constraints, not URL shapes. Stateless, resource-oriented, cacheable communication over HTTP — that's the essence.