Resources and Endpoints

# CHAPTER 5

Resources and Endpoints #

1. Introduction #

2. Learning Objectives #

• Define what a "Resource" is in the context of REST.

• Differentiate between a URL, a URI, and an Endpoint.

• Understand standard RESTful naming conventions.

• Design logical, hierarchical endpoints for complex relationships.

• Avoid common anti-patterns in endpoint design.

3. Beginner-Friendly Explanation #

• The Library is the server.

• The Books, Authors, and Members are the Resources.

• The Aisle and Shelf numbers (e.g., Aisle 5, Shelf B) are the Endpoints.

If you want to find a book, you don't wander around aimlessly; you go to the specific location where books are kept. In REST, if you want a list of users, you go directly to the /users endpoint. A clean API allows developers to guess where things are without even looking at the manual, just like a well-labeled library.

4. Real-World Examples #

• GitHub API: To get a user's repositories, the endpoint is https://api.github.com/users/octocat/repos. Notice the hierarchy: Users -> Specific User (octocat) -> Repositories.

• Stripe API: To view a specific customer, the endpoint is https://api.stripe.com/v1/customers/cus_123.

5. Detailed Code Examples #

<?php
// A simple routing concept in PHP
$method = $_SERVER[&#039;REQUEST_METHOD'];
$path = parse_url($_SERVER[&#039;REQUEST_URI'], PHP_URL_PATH);

// Endpoint: GET /users
if ($method === &#039;GET' && $path === '/users') {
    echo "Here is the list of all users.";
}

// Endpoint: GET /users/123
// Using regex to match an ID at the end of the URL
elseif ($method === &#039;GET' && preg_match('/\/users\/(\d+)/', $path, $matches)) {
    $userId = $matches[1];
    echo "Here is the data for user ID: " . $userId;
} else {
    http_response_code(404);
    echo "Endpoint not found.";
}
?>

6. Request/Response Examples #

Request:

GET /articles/10/comments HTTP/1.1
Host: api.blog.com

Response:

[
  { "id": 1, "text": "Great article!" },
  { "id": 2, "text": "I disagree with paragraph 3." }
]

7. HTTP Examples #

• GET /users (Fetch all users)

• POST /users (Create a new user)

• GET /users/5 (Fetch user #5)

• PUT /users/5 (Update user #5)

• DELETE /users/5 (Delete user #5)

8. JSON Examples #

POST to /products:

{
  "name": "Wireless Mouse",
  "price": 29.99,
  "category_id": 4
}

9. Best Practices #

• Use Nouns, Not Verbs: Use /users, not /getUsers or /createUsers. The HTTP method (GET, POST) provides the verb.

• Use Plurals: Standardize on plural nouns. Use /users, /products, and /orders instead of /user or /product.

• Keep Hierarchy Logical: For nested resources, go down one level. E.g., /users/5/orders (Orders belonging to user 5). Avoid going too deep (like /users/5/orders/12/items/4); it becomes too complex.

10. Common Mistakes #

• Action-based URLs: Creating endpoints like POST /users/5/delete. This breaks REST conventions. It should be DELETE /users/5.

• Inconsistent Pluralization: Mixing /user and /products across your API. Pick plurals and stick with them uniformly.

11. Mini Exercises #

1. 1. Look at this URL: POST /updateCustomerProfile?id=9. Rewrite it to be perfectly RESTful.

1. 2. Design the endpoint URL to fetch the list of reviews for a specific product with ID 42.

12. Coding Challenges #

1. 1. View all animals.

1. 2. Add a new animal.

1. 3. View the diet plan for the animal with ID 8.

1. 4. Remove the animal with ID 3 from the system.

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the difference between using nouns and verbs in REST endpoint design.

• Q: If an endpoint becomes too deeply nested (e.g., /authors/1/books/5/chapters/3/paragraphs), how would you refactor it to be cleaner?

• Q: Why do we prefer plural nouns (/users) over singular nouns (/user) in API design?

15. FAQs #

Q: Should endpoints be lowercase? A: Yes. Use lowercase letters and hyphens (kebab-case) for multi-word endpoints. For example, /user-profiles is preferred over /userProfiles or /User_Profiles.

16. Summary #

17. Next Chapter Recommendation #