REST & RESTful API Design
REST (Representational State Transfer) is an architectural style for designing networked applications. It relies on a stateless, client-server, cacheable communications protocol — in virtually all cases, the HTTP protocol.
What is REST?
REST defines a set of constraints to create web services that are scalable, efficient, and easy to maintain.
- Key Idea: Uses standard HTTP methods and focuses on Resources rather than operations.
- Origin: Coined by Roy Fielding in his 2000 doctoral dissertation.
Why REST Matters?
- Simplicity & Scalability: Based on standard HTTP, making it easy to grow.
- Interoperability: Works seamlessly across different platforms and languages.
- Efficiency: Leverages caching and statelessness for high performance.
REST Constraints (Core Principles)
To be considered "RESTful," an API must adhere to these six constraints:
- Client-Server Architecture: Separation of concerns. The client handles the UI, and the server handles data/storage.
- Statelessness: No client context is stored on the server between requests.
- Cacheability: Clients can cache responses to improve performance.
- Layered System: The client cannot tell if it is connected directly to the end server or to an intermediate.
- Uniform Interface: Standardized communication (resource identification, manipulation via representations).
- Code on Demand (Optional): Servers can temporarily extend client functionality by transferring executable code.
RESTful API Design Principles
1. Resource-Based Approach
Everything is a resource. You don't "Login," you create a "Session."
GET /users/{id}to retrieve a user.POST /ordersto create a new order.
2. Consistency in URL Structure
✅ Use plural nouns for collections (/users, not /user).
✅ Avoid actions in URLs: /users/{id}/activate ❌ → /users/{id} with PATCH ✅.
✅ Implement versioning: /v1/users.
Resources & Endpoints
An endpoint is a specific URL where a client interacts with a resource.
| Action | Endpoint Example |
|---|---|
| Get all products | GET https://example.com/products |
| Get product details | GET https://example.com/products/{id} |
| Add a new product | POST https://example.com/products |
| Update a product | PUT https://example.com/products/{id} |
| Partial update | PATCH https://example.com/products/{id} |
| Remove a product | DELETE https://example.com/products/{id} |
JSON vs. XML in REST APIs
While REST supports many formats, JSON is the industry standard due to its lightweight nature.
- JSON: Lightweight, faster parsing, human-readable.
- XML: Used in legacy systems, supports complex data validation (XSD).
Real-World REST API Examples
Twitter API Example
How a mobile app fetches a specific tweet.
GitHub API Example
- Get repo details:
GET /repos/{owner}/{repo} - Create an issue:
POST /repos/{owner}/{repo}/issues
Interview Questions & Answers: REST APIs
1. What is REST, and how does it differ from SOAP?
REST is an architectural style focusing on resources and HTTP methods. SOAP is a strict protocol using XML and WS-Security.
- REST: Lightweight, JSON, faster, stateless.
- SOAP: Heavy, XML-only, can be stateful, highly secure.
2. What are the six constraints of REST?
- Client-Server 2. Statelessness 3. Cacheability 4. Layered System 5. Uniform Interface 6. Code on Demand.
3. REST API vs. RESTful API?
A REST API follows some REST principles. A RESTful API strictly adheres to all constraints.
4. When would you use PUT vs. PATCH?
- PUT: Replaces the entire resource.
- PATCH: Applies a partial update (e.g., just the email).
5. What are the common status codes in REST?
200 OK,201 Created,204 No Content.400 Bad Request,401 Unauthorized,403 Forbidden,404 Not Found.500 Internal Error.
6. What is HATEOAS?
HATEOAS (Hypermedia as the Engine of Application State) means the API response includes links to other related actions/resources, allowing the client to discover the API dynamically.
7. How do you implement pagination?
Use query parameters like ?page=2&limit=10.
8. Explain REST vs. GraphQL vs. gRPC.
| Feature | REST | GraphQL | gRPC |
|---|---|---|---|
| Format | JSON | JSON | Protobuf |
| Flexibility | Fixed | Custom | Strict |
| Performance | Medium | High | Very High |
9. How do you handle versioning?
Commonly via URI (/v1/), Headers (Accept-Version: v1), or Query params (?v=1).
10. Can a REST API be stateful?
No, the constraint is statelessness. However, some use session-based auth which technically introduces state, deviating from pure REST.
Final Thoughts
REST is the dominant architectural style for the web today. Mastering its constraints and design patterns is crucial for building scalable, world-class APIs.