Skip to main content

REST

REST (Representational State Transfer) is an architectural style for designing networked applications, particularly web services. Introduced by Roy Fielding in his 2000 doctoral dissertation, REST has become the dominant approach for building web APIs due to its simplicity, scalability, and alignment with the HTTP protocol.

Core Principles​

REST is built upon six fundamental constraints:

1. Client-Server Architecture​

The client and server are separate entities that communicate over a network. The client is responsible for the user interface and user experience, while the server handles data storage and business logic. This separation allows each to evolve independently.

2. Statelessness​

Each request from client to server must contain all the information necessary to understand and process the request. The server does not store any client context between requests. Session state is kept entirely on the client.

This constraint improves:

  • Scalability: Servers don't need to maintain session state
  • Reliability: Failed requests can be easily retried
  • Visibility: Each request is self-contained and can be understood in isolation

3. Cacheability​

Responses must explicitly indicate whether they can be cached. When a response is cacheable, the client can reuse that response data for equivalent requests in the future, reducing the number of interactions needed and improving performance.

4. Uniform Interface​

REST defines a uniform interface between clients and servers, which simplifies and decouples the architecture. This constraint has four sub-constraints:

  • Resource Identification: Resources are identified using URIs
  • Resource Manipulation: Resources are manipulated through representations (typically JSON or XML)
  • Self-Descriptive Messages: Each message contains enough information to describe how to process it
  • Hypermedia: Clients interact with the application entirely through hypermedia provided dynamically by the server (HATEOAS)

5. Layered System​

The architecture can be composed of hierarchical layers, with each layer only knowing about the immediate layer it's interacting with. This allows for load balancers, proxies, and gateways to be added without affecting the client-server communication.

6. Code on Demand (Optional)​

Servers can extend client functionality by transferring executable code (e.g., JavaScript). This is the only optional constraint.

Resources and URIs​

In REST, everything is a resource—any information that can be named. Resources are identified by URIs (Uniform Resource Identifiers):

https://api.example.com/platforms
https://api.example.com/platforms/5
https://api.example.com/platforms/5/commands

Resources should be nouns, not verbs. The action is determined by the HTTP method, not the URI:

✅ Good:
GET    /platforms
POST   /platforms
GET    /platforms/5
DELETE /platforms/5

❌ Bad:
GET    /getPlatforms
POST   /createPlatform
GET    /getPlatform/5
POST   /deletePlatform/5

HTTP Methods (Verbs)​

REST leverages HTTP methods to define actions on resources:

GET​

Retrieves a representation of a resource. Should be safe (no side effects) and idempotent (multiple identical requests have the same effect as a single request).

GET /platforms/5
GET /platforms?page=1&size=10

POST​

Creates a new resource or triggers a processing action. Not idempotent—multiple identical requests may create multiple resources.

POST /platforms
Body: { "name": "Docker", "publisher": "Docker Inc." }

PUT​

Replaces an entire resource. Should be idempotent—multiple identical requests should have the same effect.

PUT /platforms/5
Body: { "name": "Docker", "publisher": "Docker Inc.", "licenseType": "Open Source" }

PATCH​

Partially updates a resource. Unlike PUT, only the fields provided in the request are updated.

PATCH /platforms/5
Body: { "licenseType": "Open Source" }

DELETE​

Removes a resource. Should be idempotent.

DELETE /platforms/5

HTTP Status Codes​

RESTful APIs use HTTP status codes to indicate the outcome of requests:

2xx Success​

  • 200 OK: Request succeeded, response contains data
  • 201 Created: Resource created successfully
  • 204 No Content: Request succeeded, no response body

3xx Redirection​

  • 301 Moved Permanently: Resource has been permanently moved
  • 304 Not Modified: Cached version is still valid

4xx Client Errors​

  • 400 Bad Request: Invalid request syntax or data
  • 401 Unauthorized: Authentication required or failed
  • 403 Forbidden: Server understood request but refuses to authorize
  • 404 Not Found: Resource doesn't exist
  • 409 Conflict: Request conflicts with current state (e.g., duplicate)

5xx Server Errors​

  • 500 Internal Server Error: Generic server error
  • 503 Service Unavailable: Server temporarily unavailable

Representations​

Resources can have multiple representations (JSON, XML, HTML, etc.). The client specifies the desired format using the Accept header:

GET /platforms/5
Accept: application/json

JSON has become the de facto standard for REST APIs due to its simplicity and ubiquity:

{
  "id": 5,
  "name": "Docker",
  "publisher": "Docker Inc.",
  "licenseType": "Open Source"
}

REST vs Other Approaches​

REST vs GraphQL​

  • REST: Multiple endpoints, fixed response structure, can over-fetch or under-fetch data
  • GraphQL: Single endpoint, client specifies exact data needed, more complex to implement

REST vs gRPC​

  • REST: Text-based (JSON), human-readable, browser-compatible, widely supported
  • gRPC: Binary (Protocol Buffers), more efficient, supports streaming, requires HTTP/2

REST vs SOAP​

  • REST: Lightweight, flexible, uses standard HTTP
  • SOAP: Heavyweight, strict standards (WS-*), includes built-in error handling

REST remains the most popular choice for web APIs due to its simplicity, flexibility, and alignment with web standards.

Further Reading​