The digital world relies heavily on communication between different systems, applications, and devices. Whether it’s a mobile application requesting data from a server, a web application interacting with a backend service, or an IoT device sending information to the cloud, APIs (Application Programming Interfaces) are the bridge that makes this communication possible. Among various architectural approaches to building APIs, REST (Representational State Transfer) has become the most widely adopted due to its simplicity, scalability, and flexibility.
This comprehensive guide explains the fundamentals of REST APIs in detail, focusing on four core areas:
- What REST Is
- HTTP Methods
- HTTP Status Codes
- Resource-Oriented URL Structure
By the end of this article, you will have a deep understanding of REST principles and how they shape modern API development.
1. What REST Is
REST, or Representational State Transfer, is an architectural style defined by Roy Fielding in his 2000 doctoral dissertation. It is not a protocol, framework, or technology; instead, it outlines a set of constraints that when followed, make systems scalable, reliable, and easy to maintain.
1.1 REST Is an Architectural Style
REST defines how systems should communicate rather than specifying a format or technology stack. RESTful systems typically use HTTP because it already has built-in capabilities that align with REST principles, but REST can theoretically be implemented over other protocols as well.
1.2 Core Characteristics of REST
REST has six formal constraints. An API that follows them is considered RESTful:
1.2.1 Client-Server Architecture
The client (frontend/UI) and server (backend logic) must be separate. This separation makes systems more modular and scalable.
1.2.2 Statelessness
Each request from a client must contain all the information needed to process it.
The server does not store session state between requests.
Statelessness ensures:
- Scalability
- Easier load balancing
- Better fault isolation
1.2.3 Cacheability
REST allows responses to be marked as cacheable.
Caching improves performance by reducing repeated requests.
1.2.4 Uniform Interface
REST uses a standardized way for systems to communicate. This is the most important constraint and includes:
- Resource identification (using URLs)
- Representations (usually JSON)
- Standard HTTP methods
- Consistent response codes
1.2.5 Layered System
The system can have multiple layers—load balancers, proxies, gateways—without exposing complexity to the client.
1.2.6 Code on Demand (Optional)
The server can send executable code (such as JavaScript) to the client.
This constraint is optional and not commonly used in REST APIs.
1.3 Why REST Became So Popular
REST dominates the API landscape for several reasons:
- Simple: Works on basic HTTP methods.
- Flexible: Supports multiple data formats (JSON, XML, HTML).
- Scalable: Statelessness and caching improve performance.
- Interoperable: Any client that understands HTTP can use a REST API.
- Widely supported: Almost every programming language has libraries to work with REST.
Because of these advantages, REST is the backbone of modern web and mobile applications.
2. HTTP Methods (GET, POST, PUT, DELETE, and Others)
REST heavily leverages HTTP methods (also called HTTP verbs) to perform actions on resources. Each method has a specific purpose and semantic meaning. Understanding these methods is critical for designing predictable and professional REST APIs.
Below is a detailed explanation of the most commonly used HTTP methods.
2.1 GET — Retrieve Data
The GET method retrieves data from the server.
Examples:
- Fetch list of users
- Fetch a specific product
- Search records
Characteristics:
- Safe: Should not modify server data.
- Idempotent: Multiple identical GET requests produce the same result.
- Cacheable: Browsers and systems can cache GET responses.
Example request:
GET /users/123
2.2 POST — Create a New Resource
The POST method sends data to the server to create a resource.
It is commonly used for:
- Creating user accounts
- Submitting forms
- Uploading files
Characteristics:
- Not idempotent: Calling POST repeatedly may create duplicate records.
- Used for actions that involve server-side change
- Often returns 201 Created with a location header
Example request:
POST /users
2.3 PUT — Update or Replace a Resource
The PUT method completely replaces a resource with new data.
Examples:
- Updating a user profile
- Replacing product information
Characteristics:
- Idempotent: Multiple identical PUT requests have the same effect.
- Requires full payload (not partial updates).
Example:
PUT /users/123
2.4 PATCH — Partially Update a Resource
The PATCH method performs partial updates.
Examples:
- Update only user email
- Change only the product price
Characteristics:
- Not always idempotent
- Updates only specific fields
Example:
PATCH /users/123
2.5 DELETE — Remove a Resource
The DELETE method removes a resource.
Example:
DELETE /users/123
Characteristics:
- Idempotent: Deleting the same resource multiple times returns the same status (usually 204 or 404).
2.6 Other Useful HTTP Methods
2.6.1 HEAD
Returns metadata of a resource without its body.
2.6.2 OPTIONS
Describes available methods for a resource.
Used in CORS (Cross-Origin Resource Sharing).
2.6.3 TRACE
Echoes the received request.
Rarely used in APIs.
3. HTTP Status Codes
Status codes are critical in REST APIs because they convey the outcome of a request. A well-designed API uses consistent and meaningful HTTP status codes.
Below is a detailed breakdown of important status code categories and commonly used codes.
3.1 1xx — Informational Codes
These codes indicate that the request was received and is being processed.
Not commonly used in REST APIs.
Examples:
- 100 Continue
- 101 Switching Protocols
3.2 2xx — Success Codes
These codes indicate that the request completed successfully.
200 OK
General success response for GET, PUT, PATCH, and DELETE.
201 Created
Used when a resource is created via POST.
202 Accepted
Request accepted but not yet processed (async operations).
204 No Content
Used for successful DELETE or update operations without a response body.
3.3 3xx — Redirection Codes
Indicate that the client must take an additional action to complete the request.
Examples:
- 301 Moved Permanently
- 302 Found
- 304 Not Modified (used with caching)
3.4 4xx — Client Error Codes
These codes indicate that the request was invalid or impossible to process.
400 Bad Request
Invalid input or syntax.
401 Unauthorized
Authentication required or failed.
403 Forbidden
Authenticated but not allowed.
404 Not Found
Resource does not exist.
409 Conflict
Data conflict, such as duplicate entries.
422 Unprocessable Entity
Validation errors.
3.5 5xx — Server Error Codes
These codes indicate the server failed to handle a valid request.
500 Internal Server Error
General server error.
502 Bad Gateway
Server received an invalid response from an upstream service.
503 Service Unavailable
Server is temporarily overloaded or down.
504 Gateway Timeout
Upstream server took too long to respond.
4. Resource-Oriented URL Structure
One of the key principles of REST is its resource-oriented approach. In REST, everything the API handles is treated as a resource, and each resource is identified with a unique URL.
Below is a detailed explanation of how to design clean, predictable, and professional REST URLs.
4.1 What Is a Resource?
A resource is anything your API manages.
Examples:
- Users
- Products
- Orders
- Blog posts
Resources should be represented as nouns, not verbs.
Bad:
/createUser
/getProducts
Good:
/users
/products
4.2 Use Plural Nouns
Plural nouns make the API consistent.
Examples:
/users
/products
/orders
When accessing a single resource:
/users/123
/products/555
4.3 Use Hierarchical (Nested) URLs Where Appropriate
Use nesting to show relationships.
Examples:
/users/123/orders
/users/123/orders/456
/products/55/reviews
Avoid deep nesting beyond two levels to keep URLs manageable.
4.4 Use Query Parameters for Filtering, Sorting, and Searching
Query parameters refine results without changing resource identity.
Examples:
/users?role=admin
/products?category=electronics&sort=price
/orders?date=2025-01-01
4.5 Do Not Use Verbs in URLs
The HTTP method should convey the action, not the URL.
Bad:
/addUser
/updateUser/123
/deleteProduct/555
Good:
POST /users
PUT /users/123
DELETE /products/555
4.6 Use Consistent Naming Conventions
Follow snake_case or kebab-case for query parameters and URLs.
Examples:
/users?status=active
/products?min_price=100
4.7 Versioning in URL
Versioning is essential for backward compatibility.
Examples:
/v1/users
/v2/products
Some APIs use headers instead of URL-based versioning, but URL versioning is the most common.
Leave a Reply