REST Architectural Principles

# CHAPTER 4

REST Architectural Principles #

1. Introduction #

2. Learning Objectives #

• Define the core architectural constraints of REST.

• Understand the concept of "Statelessness" in web APIs.

• Explain the importance of Client-Server separation.

• Understand Cacheability and Layered Systems.

• Describe the Uniform Interface constraint.

3. Beginner-Friendly Explanation #

1. 1. Client-Server Separation: The customer in the car (Client) orders food, and the workers inside (Server) prepare it. They have distinct roles.

1. 2. Statelessness: Every time a car pulls up, the worker doesn't remember what the driver ordered yesterday. The driver must provide a complete, fresh order every time.

1. 3. Cacheability: If the restaurant prepares 50 burgers in advance because they are popular, they can serve them instantly. (Caching)

1. 4. Uniform Interface: Every McDonald's drive-thru looks and works identically, no matter which state you are in. You know exactly how to use the menu and speaker.

RESTful APIs apply these same logical rules to software communication to ensure systems are scalable, fast, and reliable.

4. Real-World Examples #

• Statelessness in action: When you use a token to authenticate with an API, you send the token with *every single request*. The server does not "log you in" and remember you between requests. It verifies the token on request #1, and it verifies the exact same token on request #100.

• Layered System: When you send an API request to a large site like Twitter, it might hit a load balancer, then a proxy server, then an authentication server, before finally hitting the database server. As the client, you don't know or care about these layers; you just get your data.

5. Detailed Code Examples #

Bad (Not RESTful - Stateful):

<?php
session_start();
// Relying on server memory to know if the user is logged in
if (isset($_SESSION[&#039;user_id'])) {
    echo json_encode(["data" => "Secret info"]);
}
?>

Good (RESTful - Stateless):

<?php
// The client MUST provide an API key in the headers for EVERY request
$headers = getallheaders();
if (isset($headers[&#039;Authorization']) && $headers['Authorization'] === 'Bearer xyz123') {
    echo json_encode(["data" => "Secret info"]);
} else {
    http_response_code(401);
    echo json_encode(["error" => "Unauthorized"]);
}
?>

6. Request/Response Examples #

Response with Caching Headers:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600

{
  "company_name": "Tech Corp",
  "contact_email": "hello@techcorp.com"
}

*Because of the Cache-Control header, the client knows it doesn't need to ask for this data again for 3600 seconds (1 hour).*

7. HTTP Examples #

• To get data: Use GET

• To create data: Use POST

• To delete data: Use DELETE

# A uniform, predictable way to delete user 55
DELETE /users/55 HTTP/1.1
Host: api.example.com

8. JSON Examples #

{
  "success": true,
  "data": {
    "id": 55,
    "status": "deleted"
  }
}

9. Best Practices #

• Embrace Statelessness: Never store client context (like sessions) on the server. This makes scaling your servers incredibly easy because any server can handle any request.

• Standardize Responses: Ensure that if your API returns an error, the JSON error format is identical whether it's an authentication error or a database error.

• Leverage HTTP Caching: For data that rarely changes (like a list of countries), use cache headers to reduce server load.

10. Common Mistakes #

• Using Sessions for APIs: This is the #1 mistake PHP developers make when transitioning from web pages to APIs. Sessions bind a client to a specific server memory block, destroying RESTful statelessness.

• Ignoring Uniform Interface: Creating messy URLs like GET /deleteUser?id=5. A uniform interface would dictate DELETE /users/5.

11. Mini Exercises #

1. 1. Look up the term "Load Balancer." How does a layered system architecture allow a load balancer to distribute traffic across 10 different backend servers?

1. 2. Review the API documentation of a public API (like GitHub). Notice how predictable their URLs and HTTP methods are.

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Can you list and explain at least 3 of the architectural constraints of REST?

• Q: Explain why statelessness makes it easier to scale a web application horizontally (adding more servers).

• Q: Describe how a Layered System benefits security and performance.

15. FAQs #

Q: If the server is stateless, how do shopping carts work via APIs? A: The client (e.g., the mobile app) remembers the cart contents, or the cart is saved to a database table linked to the user's ID. When checking out, the client sends the entire cart payload, or tells the server "checkout the cart for user 123." The server doesn't hold the cart in temporary memory.

16. Summary #

17. Next Chapter Recommendation #