REST

What is it

REST stands for Representational State Transfer. It’s a set of principles for designing web APIs that uses the HTTP protocol 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 Principles

Principle	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 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	Faster, strict typing, 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.

Related Terms

• [[API]] - The general concept; REST is the most popular design style
• [[Endpoint]] - Each URL in a REST API is an endpoint
• [[JWT]] - The standard for authenticating REST API requests
• [[Microservices]] - Architecture where each service exposes its own REST API

---

Additional Resources:

• REST API Tutorial - Practical guide
• HTTP Status Codes - Reference for all HTTP codes