REST
ActiveREST (Representational State Transfer) is an architectural style for distributed hypermedia systems defined by Roy Fielding in his 2000 doctoral dissertation. REST uses HTTP as transport and treats every piece of data as a resource identified by a URL. Clients interact with resources via standard HTTP methods (GET, POST, PUT, PATCH, DELETE). REST is the dominant API style – 92% of organizations use REST APIs as of 2025.
In one line
REST (Representational State Transfer) is Roy Fielding's 2000 architectural style for APIs built on HTTP. Resources are identified by URLs; clients manipulate them with HTTP methods (GET/POST/PUT/PATCH/DELETE). Six constraints: uniform interface, stateless, client-server, cacheable, layered system, code-on-demand (optional). REST APIs use JSON (or XML) as the representation format. REST is the dominant API style with 92% enterprise adoption – every public API from Stripe to GitHub to Twilio uses REST.
Quick Reference
| Field | Size | Description |
|---|---|---|
| Resources | Nouns, not verbs | Every REST resource is a noun identified by a URL: /users, /orders/123, /products/456/reviews. Never use verbs in URLs: /getUser or /createOrder violates REST. |
| HTTP methods | GET/POST/PUT/PATCH/DELETE | GET: read. POST: create. PUT: replace entirely. PATCH: partial update. DELETE: remove. Use the right method – idempotency and safety matter for caching and retry logic. |
| Status codes | 2xx/3xx/4xx/5xx | 200 OK, 201 Created, 204 No Content. 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity. 500 Internal Server Error. |
| Stateless | No session state | Each request must contain all context needed. No server-side session. Auth via Authorization header (Bearer token, API key) on every request. |
| Content-Type | application/json | application/json is the standard for REST APIs. application/xml for legacy enterprise. Always set Content-Type on request bodies and Accept on requests. |
| Versioning | URL or header | URL prefix: /v1/users (most common). Accept header: Accept: application/vnd.api+json;version=2. Query param: /users?version=2 (not recommended). Pick one strategy and be consistent. |
| HATEOAS | Hypermedia controls | Hypermedia As The Engine Of Application State – responses include links to related actions. Rarely implemented in practice despite being in Fielding's original constraints. |
| Idempotency | GET/PUT/DELETE | GET, PUT, DELETE are idempotent – same request produces same result. POST is not idempotent. PATCH may or may not be. Use Idempotency-Key header for POST retry safety (Stripe pattern). |
Key Characteristics
Resource-oriented
Every entity is a resource with a URL. Collections (/users) and singletons (/users/123). Resources nest (/users/123/orders). URLs are permanent identifiers.
Stateless sessions
No server-side session state. Every request is independent. Scales horizontally – any server can handle any request. Auth context carried in the Authorization header.
HTTP caching
GET responses can be cached by browsers, CDNs, and proxies using Cache-Control, ETag, and Last-Modified headers. Correctly designed REST APIs are naturally cacheable.
Over/under-fetching
REST endpoints return fixed shapes – clients may get too much (over-fetch) or need multiple requests (under-fetch). GraphQL was created to solve this. For complex UIs, consider a BFF (Backend For Frontend) pattern.
Message Format
# REST API request examples
# GET – read a collection
GET /api/v1/users?page=2&limit=20&sort=created_at HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json
# POST – create a resource
POST /api/v1/users HTTP/1.1
Content-Type: application/json
Idempotency-Key: uuid-abc-123
{
"name": "Alice",
"email": "[email protected]",
"role": "admin"
}# 201 Created response
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/usr_123
{
"id": "usr_123",
"name": "Alice",
"email": "[email protected]",
"role": "admin",
"createdAt": "2026-07-24T10:00:00Z"
}
# 422 Validation error (standard error shape)
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
}
}