REST

What is it

REST stands for Representational State Transfer. It’s an architectural style described by Roy Fielding in his doctoral dissertation (University of California, Irvine, 2000). In practice it’s used to design web APIs over HTTP so that any client (web, mobile, other servers) can communicate with the server predictably.

An API following these principles is called RESTful or a REST API.

The 6 REST Constraints

Constraint	Description
Stateless	Each request contains all necessary information — the server doesn’t “remember” previous requests
Client-Server	Client and server are independent — the client doesn’t know how the backend works
Uniform Interface	Resources with consistent URLs and standard HTTP methods
Cacheable	Responses can indicate whether they can be cached
Layered System	The client doesn’t know if there are proxies or load balancers between them
Code on Demand (optional)	The server can send executable code to the client

HTTP Methods in REST

Method	Operation	Example
GET	Retrieve data	`GET /users/123` → returns user 123
POST	Create new resource	`POST /users` → creates a new user
PUT	Fully update	`PUT /users/123` → replaces user 123
PATCH	Partially update	`PATCH /users/123` → updates only the email
DELETE	Remove	`DELETE /users/123` → deletes user 123

RESTful URL Design

A well-designed REST API uses nouns (not verbs) in URLs:

✅ RESTful:
GET    /products           → list of products
GET    /products/42        → product with ID 42
POST   /products           → create product
PUT    /products/42        → update product 42
DELETE /products/42        → delete product 42

❌ Not RESTful:
GET /getProducts
GET /getProduct?id=42
POST /createProduct
GET /deleteProduct?id=42

Responses and HTTP Status Codes

REST APIs use standard HTTP status codes:

Code	Meaning	When used
200 OK	Success	Successful GET or PUT
201 Created	Resource created	Successful POST
204 No Content	Success with no body	Successful DELETE
400 Bad Request	Invalid request	Missing or incorrect data
401 Unauthorized	Not authenticated	No token or invalid token
403 Forbidden	No permissions	Valid token but no access
404 Not Found	Doesn’t exist	Resource not found
500 Internal Server Error	Server error	Internal bug

Real-World REST Response Example

// GET /orders/789
{
  "id": 789,
  "status": "preparing",
  "customer": {
    "id": 123,
    "name": "Ana García"
  },
  "items": [
    { "product": "Laptop", "quantity": 1, "price": 1299.99 }
  ],
  "total": 1299.99,
  "createdAt": "2026-03-10T14:30:00Z"
}

REST vs Other Alternatives

Technology	Ideal use case	Key difference
REST	Most web APIs	Simple, standard, broad support
GraphQL	APIs with complex, variable data	Client chooses exactly which fields to receive
gRPC	Internal microservice communication	Generally more efficient (HTTP/2 + Protocol Buffers), typed contracts, less human-readable
SOAP	Legacy or enterprise systems	More verbose, stricter XML protocol

Why It Matters

When a development team says “we’ll build a REST API,” they’re making decisions that affect:

How easy it is to integrate the system with other tools
Performance and scalability
Documentation and maintainability
Developer experience for API consumers

A well-designed REST API lasts for years and can be consumed by web, mobile, and other systems without changes.

API - The general concept; REST is the most popular design style
Endpoint - Each URL in a REST API is an endpoint
JWT - A widely used token format for authenticating REST API requests
Microservices - Architecture where each service exposes its own REST API

Additional Resources:

REST API Tutorial - Practical guide
MDN - HTTP response status codes - Reference for all HTTP codes