REST (Representational State Transfer)
• Definition: REST is an architectural style for designing networked applications. It
uses HTTP to interact with resources and ensures scalability and simplicity in
communication.
• Key Concept: Resources are identified using URIs (Uniform Resource Identifiers),
and HTTP methods perform operations on them.
REST Principles: To design a RESTful API, these principles are followed:
Principle Description
Resource
Use URIs to identify resources (e.g., /api/users/1).
Identification
Resources can have multiple representations (e.g., JSON, XML) but are abstracted
Representation
as one logical resource.
The server does not store client state. Each request is independent and contains all
Statelessness required data, including authentication. There is no need to maintain a continuous
connection between client and server, which implies a greater tolerance to failure. I
Use HTTP methods (GET, POST, PUT, DELETE, etc.) appropriately to perform
HTTP Methods
operations on resources.
Ensure standard communication between clients and servers (consistent URIs, status
Uniform Interface
codes, and request/response formats).
Implement caching wherever possible to reduce server load and improve client
Cacheable
performance.
Hypermedia as the Engine of Application State: Clients can discover actions
HATEOAS (Optional)
dynamically through links provided in the responses.
Example of RESTful API
Base URL: http://example.com/api/
Operation HTTP Method URI Description
Get all users GET /users Retrieve a list of all users.
Get a specific user GET /users/{id} Retrieve a user by ID.
Create a new user POST /users Add a new user.
Update an existing user PUT /users/{id} Update user details.
Delete a user DELETE /users/{id} Delete a user by ID.
Guidelines for designing URI structures
1. Use Nouns, Not Verbs
URIs should represent resources, not actions.
Good: /products, /users/{id}/orders
Bad: /getProducts, /createUser
2. Use Plural Nouns
Use plural nouns for collections of resources.
Good: /books, /employees
Bad: /book, /employee
3. Use Consistent Naming Conventions
Use lowercase letters and hyphens (-) to separate words. Avoid underscores (_) or mixed
case.
Good: /user-profiles
Bad: /UserProfiles, /user_profiles
4. Hierarchical Structure
Use a clear hierarchy to represent relationships between resources.
Good: /users/{userId}/orders/{orderId}
Bad: /users-orders/{userId}/{orderId}
5. Avoid File Extensions
Do not include file extensions like .html, .xml, or .json. Let content negotiation decide the
format.
Good: /products
Bad: /products.json
6. Use Query Parameters for Filtering, Sorting, and Pagination
Use query parameters for optional data that modifies the resource representation.
Good: /products?category=electronics&sort=price&page=2
Bad: /products/category/electronics/sort/price/page/2
7. Keep URIs Short and Meaningful
Avoid long, complex URIs. Focus on clarity.
Good: /api/v1/orders
Bad: /api/v1/order_management_system/resources/orders
8. Version Your API
Include the version number in the URI for backward compatibility.
Good: /api/v1/products
Bad: /products
9. Use HTTP Methods Appropriately
Use HTTP verbs to indicate actions:
GET: Retrieve data (/products)
POST: Create a new resource (/products)
PUT: Update a resource (/products/{id})
DELETE: Remove a resource (/products/{id})
10. Avoid Redundant Information
Don’t repeat information in the URI.
Good: /users/{userId}/orders
Bad: /users/{userId}/user-orders
Example of a Well-Designed URI Structure
For a Bookstore API:
Resource HTTP Method URI
Get all books GET /books
Get a book GET /books/{bookId}
Add a book POST /books
Update a book PUT /books/{bookId}
Delete a book DELETE /books/{bookId}
Get reviews for a book GET /books/{bookId}/reviews
