REST is the most common architectural style for building web APIs today. But "having HTTP endpoints" doesn't make an API RESTful — REST is a set of principles for how to model and expose resources. Understanding those principles is what separates a predictable, easy-to-consume API from a mess.
The API as a contract
An API is a contract between whoever provides it and whoever consumes it. It defines which operations exist, what each one expects to receive and what it returns. If the contract is clear and stable, different teams (or different companies) can work together without agreeing on anything beyond the documentation. That contract runs on top of HTTP — it's worth reviewing how the web works before moving on.
Resources are nouns
The core principle of REST is to think in terms of resources: things from your domain, expressed as plural nouns. /products, /users, /orders. What you do with the resource is expressed by the HTTP verb, not by the URL. That's why /createProduct is not RESTful — the "create" should be a POST /products.
HTTP verbs and the endpoint table
| Verb | Endpoint | Action |
|---|---|---|
| GET | /products | Lists all products |
| GET | /products/42 | Fetches product 42 |
| POST | /products | Creates a new product |
| PUT | /products/42 | Replaces the whole of product 42 |
| PATCH | /products/42 | Updates part of product 42 |
| DELETE | /products/42 | Removes product 42 |
Statelessness and representations
REST is stateless: each request carries everything the server needs to process it. The server doesn't keep track of "where you were" between calls. That's what allows horizontal scaling (any server can handle any request). The resource itself is abstract; what travels over the wire is a representation of it, almost always in JSON:
GET /products/42
200 OK
{
"id": 42,
"name": "Mechanical keyboard",
"price": 350.00,
"inStock": true
}Correct status codes
Using the right status code is part of the contract. In interviews you're often asked to explain the families: 2xx success (200 OK, 201 Created), 4xx client error (400 invalid, 401 unauthenticated, 403 forbidden, 404 not found), 5xx server error. Returning 200 OK with an "error happened" message inside the body is a classic sign of a poorly built API.
Safe and idempotent methods
Two important concepts: a method is safe if it doesn't change data (GET). It is idempotent if repeating it has the same effect as doing it once (GET, PUT, DELETE). POST is not idempotent — two POSTs create two resources. This notion comes back when we talk about resilience and retries.
What makes an API RESTful isn't the technology, but the discipline: resources as nouns, HTTP verbs doing the work, statelessness and honest status codes.
What makes an API "not RESTful"
Warning signs: verbs in the URL (/getProduct), everything via POST, status always 200, or keeping session state on the server between calls. Day to day, this shows up when an API "works" but is unpredictable — each endpoint has its own logic and you have to read the code to understand it.
Conclusion
REST is less about rigid rules and more about predictability. Model resources, use HTTP verbs correctly, keep the server stateless and be honest with your status codes. An API that follows this is easy to consume, document and scale — and shows that you understand the contract behind the web.