Post 40 · Web Engineering

REST API

Representational State Transfer — Roy Fielding's 2000 doctoral dissertation defined an architectural style for distributed hypermedia systems. Today it powers over 83% of all public APIs.

83%

APIs are REST-based

6

Architectural constraints

5

Core HTTP methods

60+

HTTP status codes

2000

Fielding's dissertation

    REST is not a protocol — it's an architectural style. A REST API is any HTTP API that follows Fielding's 6 constraints. It has no official spec, no WSDL, no contract — just conventions that make systems scalable, stateless, and interoperable.
  

API = Interface

An API (Application Programming Interface) is a contract between a server and a client. The server exposes resources; the client consumes them. REST defines how that contract is structured using HTTP.

Resources, not Actions

In REST, everything is a resource — a user, an order, a product. You identify resources with URLs and manipulate them with HTTP verbs (GET, POST, PUT, DELETE). Actions are verbs; resources are nouns.

Representations

A resource has state, and a REST response transfers a representation of that state — usually JSON or XML. The server doesn't send the resource itself; it sends a snapshot of its current state.

How a REST Request Works

// 1. Client identifies a resource by URL
GET https://api.example.com/users/42

// 2. Server returns a JSON representation of the resource's current state
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Bhaskarjit",
  "email": "bhaskarjit@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}
    

Who invented REST and why? ›

Roy Fielding co-wrote the HTTP/1.1 specification and needed a way to describe and evaluate web architectures. His 2000 PhD dissertation at UC Irvine introduced REST as a description of the web's own architecture — and later, as a design guide for APIs that scale like the web itself. The dissertation is publicly available and is still the definitive reference.

Section 2

The 6 Architectural Constraints

An API is only truly RESTful if it follows all six of Fielding's constraints. Miss one and it's just "an HTTP API".

Click a constraint below to explore it

Each constraint adds a specific property to the system — scalability, visibility, simplicity, or reliability.

    HATEOAS (Hypermedia As The Engine Of Application State) — the 6th constraint — is the most misunderstood and least implemented. A truly RESTful API embeds links in responses telling clients what actions are possible next, without clients needing prior knowledge of the API structure.
  

Section 3

Anatomy of a REST Request & Response

Every HTTP transaction has the same structure. Understanding each part is the foundation of working with any API.

URL Anatomy

https://api.example.com/v2/users/42/orders?status=pending&limit=10

SCHEME

https://

Protocol — always HTTPS in production

HOST

api.example.com

Base URL — identifies the server

PATH

/v2/users/42/orders

Resource path — version/collection/id/sub-resource

QUERY PARAMS

?status=pending&limit=10

Filtering, sorting, pagination

Section 4

HTTP Methods — The Verbs of REST

HTTP methods define the action performed on a resource. Choosing the right method is the first rule of good API design.

Method Properties

Method	Safe?	Idempotent?	Has Body?	Typical Use
GET	✓ Yes	✓ Yes	✗ No	Retrieve a resource
POST	✗ No	✗ No	✓ Yes	Create a new resource
PUT	✗ No	✓ Yes	✓ Yes	Replace full resource
PATCH	✗ No	~ Usually	✓ Yes	Partial update
DELETE	✗ No	✓ Yes	✗ Rarely	Remove a resource

      Safe: A method is "safe" if it doesn't modify server state. GET and HEAD are safe — calling them a thousand times has no side effects. Safe methods can be freely cached and prefetched.
    

      Idempotent: A method is "idempotent" if calling it N times produces the same result as calling it once. DELETE /users/42 is idempotent — the user is gone regardless of how many times you call it.
    

Section 5

HTTP Status Codes

The server's response always includes a 3-digit status code. It tells the client exactly what happened — success, error, redirect, or something unexpected.

Section 6

URL Design — Nouns, Not Verbs

Good REST URL design makes an API intuitive. The single most important rule: URLs identify resources (nouns), HTTP methods express actions (verbs).

✗ Bad — Verbs in URLs

GET  /getUser?id=42
POST /createOrder
POST /deleteUser?id=5
GET  /getAllProducts
POST /updateUserEmail
      

✓ Good — Nouns + HTTP Verbs

GET    /users/42
POST   /orders
DELETE /users/5
GET    /products
PATCH  /users/42
      

Standard Resource Patterns

Pattern	Example	Meaning
Collection	`GET /users`	List all users
Single resource	`GET /users/42`	Get user with ID 42
Create	`POST /users`	Create a new user
Replace	`PUT /users/42`	Replace user 42 entirely
Partial update	`PATCH /users/42`	Update specific fields of user 42
Delete	`DELETE /users/42`	Delete user 42
Sub-resource	`GET /users/42/orders`	List orders belonging to user 42
Filter	`GET /orders?status=pending`	Filter orders by status
Pagination	`GET /products?page=2&limit=20`	Page 2, 20 items per page
Versioning	`GET /v2/users`	Version 2 of the users endpoint

Use plural nouns for collections›

/users not /user. Collections are plural. This makes it unambiguous: /users returns many, /users/42 returns one.

Use kebab-case for multi-word paths›

/blog-posts not /blogPosts or /blog_posts. URLs are case-insensitive; kebab-case is the convention.

Versioning strategy›

Three common approaches: (1) URL path: /v1/users — most visible, easy to test in browser. (2) Query param: /users?v=1. (3) Header: Accept: application/vnd.api+json;version=1. URL path versioning is the most widely adopted.

Nesting depth — how deep to go?›

Never nest more than 2 levels deep. /users/42/orders/7 is acceptable. /users/42/orders/7/items/3/reviews is too deep — flatten it to /reviews?item_id=3.

Query params vs path params›

Path params identify a specific resource: /users/42. Query params filter, sort, or paginate: /users?role=admin&sort=created_at. Never put filtering logic in path params.

What about actions that aren't CRUD?›

Some actions don't map to CRUD. Use a sub-resource that reads as a noun: POST /users/42/activation (activate user) or POST /payments/42/refund. Avoid verbs — treat the action itself as a noun resource.

Section 7

Authentication & Authorization

REST is stateless — the server holds no session. Every request must carry its own credentials. Three dominant patterns.

Authentication vs Authorization

Authentication = Who are you? (identity)

Authorization = What are you allowed to do? (permissions)

Both must be checked on every request — REST's statelessness means no session can carry either.

Always HTTPS

API keys and tokens are credentials. Sending them over plain HTTP exposes them to anyone with network access. HTTPS encrypts the entire request — headers, body, and URL query parameters. No exceptions.

Rate Limiting

Protect the API from abuse. Common headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1700000000
Return 429 Too Many Requests when exceeded.

Section 8

REST vs GraphQL vs gRPC vs SOAP vs MCP

REST is not the only option. Choosing the right API style depends on your use case — including AI-native protocols like MCP.

Style	Protocol	Format	Best For	Overhead
REST	HTTP/1.1, HTTP/2	JSON, XML	Public APIs, web/mobile	Low
GraphQL	HTTP/1.1	JSON	Complex data, flexible clients	Medium
gRPC	HTTP/2	Protobuf (binary)	Microservices, low latency	Very Low
SOAP	HTTP, SMTP, TCP	XML (strict schema)	Enterprise, banking, legacy	High
WebSocket	WS / WSS	Any	Real-time, bidirectional	Low (per msg)

Section 9

Best Practices Checklist

Production-grade REST APIs follow these rules. Check off what your API already does.

Error Response Format

Always return structured error bodies — never just a status code.

HTTP/1.1 404 Not Found

{
  "error": {
    "code":    "USER_NOT_FOUND",
    "message": "No user with id=99",
    "docs":    "https://docs.example.com/errors"
  }
}
      

Pagination Response

Always paginate list endpoints — never return unbounded arrays.

HTTP/1.1 200 OK

{
  "data": [...],
  "pagination": {
    "page":    2,
    "limit":   20,
    "total":   347,
    "next":    "/users?page=3&limit=20"
  }
}
      