REST
Representational State Transfer, often referred to as REST, is an architectural style used to design web services. It uses a stateless communication model between clients and servers, relies on standard HTTP methods, and focuses on simple but powerful conventions. These notes explore the core principles of REST, examine its components, illustrate how requests flow, and include examples of building and interacting with a RESTful API.
REST (Representational State Transfer)
REST emphasizes a uniform way for clients and servers to exchange representations of resources. The approach fosters decoupled systems that are easier to maintain, scale, and evolve over time.
The diagram below outlines how a client typically makes a request to a RESTful service, and how the server responds:
+---------------------+ +----------------------+
| | | |
| REST Client | | RESTful API |
| (Web, Mobile, etc.)| | Server |
+---------------------+ +----------------------+
|| ||
|| 1. Client sends a HTTP ||
|| request (GET, POST, ||
|| PUT, DELETE) ||
\/ \/
+---------------------+ +-----------------------+
| | | |
| Prepare HTTP | | Process HTTP Request |
| Request with URL, |-----------------> | & Determine Response |
| Headers, and Body | | (Fetch, Create, |
| (if applicable) | | Update, Delete Data) |
| | | |
+---------------------+ +-----------------------+
||
|| 2. Server processes
|| the request and
\/ prepares a response
+----------------------+ +----------------------+
| | | |
| Receive & Process | | Send HTTP Response |
| HTTP Response | <---------------| with Status Code, |
| (Data, Status Code) | | Headers, and Body |
| | | (if applicable) |
+----------------------+ +----------------------+
||
|| 3. Client uses the
|| received data
\/
+----------------------+
| |
| Display/Use Data |
| (Render, Trigger) |
| |
+----------------------+
This flow shows how a request starts with the client, moves to the server, then returns with a response containing data and status information. The client then processes the response for display or further actions.
Core Principles of REST
REST is built upon certain guiding principles that shape how a client and server communicate. These principles ensure a scalable, reliable, and efficient system.
Client-Server Architecture
A client-server model means the client handles presentation (for example, a web page or mobile app), while the server deals with data storage and manipulation. When the client and server are properly separated, each side can scale or change independently. This arrangement can be represented with a simple performance equation for total request latency:
T_total = T_client + T_server
T_client accounts for client-side processing, and T_server measures server-side handling. Keeping these roles distinct prevents either side from unduly affecting the other’s performance.
Statelessness
A stateless protocol means that every request contains all the information needed for the server to process it. The server does not store session data. One way to quantify server memory usage is:
M_active = R_requests * (D_server / T_stateless)
R_requests is the request rate, D_server is the duration of server processing, and T_stateless is the time factor associated with not storing state. Statelessness helps keep M_active low and makes the system simpler to maintain.
Cacheable
REST encourages caching of responses to reduce unnecessary calls and lower bandwidth usage. A simple formula for cache effectiveness is:
L_final = L_initial * (1 - C_hitRate)
L_initial is the original load (requests per second), C_hitRate is the fraction of requests served from the cache, and L_final is the remaining load after caching. The ASCII diagram below illustrates basic caching:
Client Server
| |
GET | ---------------> | Resource
| <--------------- | Representation
| |
| Cache response |
| for some time |
| |
| Use cached |
GET | response |
| if allowed |
| |
Layered System
Layering allows you to insert intermediaries (like proxies, firewalls, or load balancers) between the client and server without the client needing to know. Each layer interacts only with the layer directly before or after it. This modularity makes it easier to scale components, introduce caching servers, or handle security in separate layers.
Uniform Interface
A uniform interface simplifies how clients interact with servers because the same conventions apply everywhere. Resources are identified by URIs, and actions are performed through well-known HTTP methods (GET, POST, PUT, DELETE, and so forth). Uniformity increases predictability and reduces the learning curve for developers using the API.
Components of a RESTful System
A RESTful approach identifies resources, manipulates those resources with standard HTTP methods, and communicates success or failure with standardized status codes.
Resources
Resources are anything of interest that can be named, such as users, orders, articles, or blog posts. Each resource is usually identified by a URI like /users/123 or /posts/42.
Request Methods
Common HTTP methods include GET for retrieval, POST for creation, PUT for updates, and DELETE for removals. Some APIs also use PATCH for partial updates, but GET, POST, PUT, and DELETE remain the core.
Response Codes
HTTP status codes convey the result of a request. A 200 range code means success, 400 range means client error, and 500 range means server error. Familiar codes include 200 (OK), 201 (Created), 404 (Not Found), and 500 (Internal Server Error).
REST vs SOAP
REST generally consumes fewer resources and uses less overhead than SOAP, making it a popular choice for modern web APIs. SOAP supports protocols beyond HTTP (such as SMTP), integrates standards for security and transactions, but can be more verbose.
Creating a RESTful API
Designing a RESTful API involves setting up endpoints for resources, determining how HTTP methods map to operations, and deciding on representations like JSON or XML. Maintaining statelessness and offering caching helps keep performance optimal.
These examples demonstrate how to create, read, update, and delete blog posts through a hypothetical RESTful service. Each code example is shown with the resulting output and a short interpretation.
POST - Create a new post
POST /posts
curl -X POST -H "Content-Type: application/json" \
-d '{"title":"My First Blog Post","content":"This is my first blog post."}' \
http://example.com/posts- Example output:
{ "id": 1, "title": "My First Blog Post", "content": "This is my first blog post." } - Interpretation of the output:
The server created a new post with an assigned ID (1). The response often comes with a 201 Created status code, indicating a successful resource creation.
GET - Retrieve all posts
GET /posts
curl -X GET http://example.com/posts- Example output:
[ { "id": 1, "title": "My First Blog Post", "content": "This is my first blog post." }, { "id": 2, "title": "Another Post", "content": "More content." } ] - Interpretation of the output:
The response includes an array of posts. A 200 OK status code means the request was successful.
GET - Retrieve a specific post
GET /posts/{id}
curl -X GET http://example.com/posts/1- Example output:
{ "id": 1, "title": "My First Blog Post", "content": "This is my first blog post." } - Interpretation of the output:
The server returned the post identified by ID 1. This also typically comes with a 200 OK status code.
PUT - Update a post
PUT /posts/{id}
curl -X PUT -H "Content-Type: application/json" \
-d '{"title":"My Updated Blog Post","content":"Updated content."}' \
http://example.com/posts/1- Example output:
{ "id": 1, "title": "My Updated Blog Post", "content": "Updated content." } - Interpretation of the output:
The server updated the existing post with new title and content. A 200 OK or 204 No Content status code may be returned.
DELETE - Delete a post
DELETE /posts/{id}
curl -X DELETE http://example.com/posts/1- Example output:
(No response body) - Interpretation of the output:
The post with ID 1 was removed. A 204 No Content code is typically returned to indicate success. Retrieving the post again would yield a 404 Not Found error.
Common Commands with curl
curl is a popular command-line tool for sending HTTP requests to REST endpoints. The table below describes a few commonly used options:
| Option | Description |
|---|---|
| -X METHOD | Specifies the HTTP method (GET, POST, PUT, DELETE, etc.) |
| -H | Adds extra HTTP headers |
| -d | Sends data in the request body (for POST, PUT, etc.) |
| -i | Includes HTTP response headers in the output |
| -v | Shows verbose (detailed) request/response information |
Best Practices for REST API Design
A few guidelines improve the usefulness and maintainability of RESTful services:
- Version your endpoints so existing clients are not broken by changes.
- Handle errors gracefully by using clear status codes and messages.
- Use HTTPS to protect data in transit, and rely on token-based authentication or OAuth for secure access.
- Split large data sets through pagination, filtering, or searching to keep responses manageable.
- Document your endpoints, request formats, and response examples so developers can integrate quickly.