Chapter 3 - Understanding REST Architectural Principles

Understanding REST Architectural Principles

Before building APIs in ASP.NET Core, it is crucial to understand the architectural style that powers almost every modern API today — REST (Representational State Transfer). REST defines how systems communicate over the web using simple and scalable principles. This chapter provides a deep dive into REST fundamentals, conventions, best practices, and real examples that you will apply throughout the entire API development process.

1. What is REST?

REST is an architectural style for designing networked applications. It relies on the HTTP protocol and models API endpoints as resources. REST is not a standard or protocol — it is a set of constraints that guide how a well-designed API should behave.

Key goals of REST:

Scalability
Performance
Simplicity
Loose coupling
Reliability

REST APIs are widely used by:

Web applications
Mobile apps
Microservices
IoT devices
Third-party integrations

2. The Six REST Architectural Constraints

A true RESTful API follows six architectural constraints. These constraints ensure that the API is scalable, modifiable, and simple.

2.1. Client–Server

Client and server are separate. The client handles UI/UX and requests resources. The server processes requests and returns responses.

2.2. Statelessness

Each request from the client must contain all information needed for the server to process it. The server does not store session or state between requests.

2.3. Cacheability

RESTful responses should define whether they are cacheable. This improves performance.

2.4. Uniform Interface

REST APIs must have a consistent and predictable structure.

2.5. Layered System

A REST system can have multiple layers (load balancer, gateways, proxies) without affecting clients.

2.6. Code on Demand (optional)

Servers can optionally send executable code to clients, such as JavaScript. This is rarely used in APIs today.

3. HTTP Methods in REST

REST uses standard HTTP verbs to perform actions on resources.

HTTP Method	Purpose	Example
GET	Retrieve data	/api/products
POST	Create new resource	/api/products
PUT	Update entire resource	/api/products/10
PATCH	Update partial resource	/api/products/10
DELETE	Delete resource	/api/products/10

Example: GET all products (curl)


curl -X GET https://localhost:7010/api/products

Example: POST create a new product (curl)


curl -X POST https://localhost:7010/api/products \
-H "Content-Type: application/json" \
-d '{ "name": "Laptop", "price": 55000 }'

4. REST Resource Naming Conventions

Your API endpoints should represent resources (nouns), not actions (verbs).

Good Examples:


/api/users
/api/users/15
/api/orders/100/items

Bad Examples (avoid verbs):


/api/getAllUsers
/api/createUser
/api/updateOrder

Plural Nouns Rule

Always use plural for collections:

/api/products

Filtering, Sorting & Searching Examples


/api/products?category=mobile
/api/products?sort=price_desc
/api/products?search=iphone
/api/orders?date=2024-01-01

5. HTTP Status Codes (REST Best Practices)

Good APIs return the correct status code for every scenario.

Status Code	Meaning	When to Use
200 OK	Success	GET successful
201 Created	Resource created	POST successful
204 No Content	No response body	DELETE or PUT successful
400 Bad Request	Invalid input	Validation error
401 Unauthorized	Not authenticated	No token / invalid token
403 Forbidden	No permission	User authenticated but not authorized
404 Not Found	Resource not found	ID not found
500 Internal Server Error	Unexpected server issue	Unhandled exception

6. Sample REST Request & Response

Example GET Response (JSON):


{
  "id": 10,
  "name": "Wireless Mouse",
  "price": 899,
  "category": "Electronics"
}

Example Error Response:


{
  "status": 400,
  "message": "Invalid product ID",
  "errors": {
    "id": ["ID must be greater than 0"]
  }
}

7. Understanding Idempotency

Idempotency means that making the same request multiple times results in the same outcome.

GET → Idempotent
PUT → Idempotent
DELETE → Idempotent
POST → Not idempotent (creates new resources)

Example: PUT idempotency


PUT /api/users/10
{
  "name": "Amit",
  "email": "amit@example.com"
}

Making this request 10 times updates the same object 10 times — result remains stable.

8. Statelessness in REST

The server does not store session data. Every request must contain full context.

Example: Sending Token with Every Request


GET /api/orders
Authorization: Bearer

9. REST vs SOAP vs GraphQL (Quick Comparison)

Feature	REST	SOAP	GraphQL
Protocol	HTTP	XML-based protocol	Single endpoint
Format	JSON	XML	JSON
Flexibility	High	Strict	Very High
Use Case	APIs for web/mobile	Financial/Enterprise	Complex querying

Conclusion

Understanding REST principles is essential before building APIs in .NET. By following proper resource naming, using the right HTTP verbs, respecting status codes, maintaining statelessness, and returning structured responses, you will build APIs that are predictable, scalable, and easy to maintain.

In the next chapter, we will explore the ASP.NET Core API project structure in detail, and understand how .NET implements REST behind the scenes.

IndianTechnoEra