CHAPTER 05
Beginner
Designing API Resources and Endpoints
Updated: May 14, 2026
30 min read
# CHAPTER 5
Designing API Resources and Endpoints
1. Introduction
The hallmark of a professional REST API is an elegant, predictable URL structure. When another developer looks at your API endpoints, they should intuitively understand exactly what the API does without reading a manual. In REST, URLs represent Resources (Nouns), while the HTTP Methods (GET, POST, PUT) represent the Actions (Verbs). In this chapter, we will master the art of resource naming, define structural conventions, and learn how to design complex nested relationships.2. Learning Objectives
By the end of this chapter, you will be able to:- Understand the difference between Noun-based REST and Verb-based RPC.
- Apply standard naming conventions to REST API endpoints.
- Design URLs for collections and specific single resources.
- Architect nested resource endpoints (e.g., Comments belonging to a Post).
- Differentiate between path parameters and query parameters.
3. Beginner-Friendly Explanation
Imagine a library.- Bad API Design: You walk in and see signs that say: "Go Here to Get Books", "Desk for Returning Books", "Office for Deleting Members". It's chaotic.
- Good REST Design: You walk in and see a section simply labeled: "Books".
- If you want a book, you walk to the "Books" section and take one (GET).
- If you want to donate a book, you walk to the "Books" section and drop it off (POST).
- If a book is damaged, you walk to the "Books" section and replace it (PUT).
In REST, the URL is just the destination (/api/books). Your action is defined by the HTTP verb you use when you get there.
4. The Golden Rule: Nouns, Not Verbs
The most common mistake beginners make is putting verbs in their URLs. This is called RPC (Remote Procedure Call) style, not REST.BAD (Verb-based URLs):
-
/api/getAllUsers
-
/api/createNewUser
-
/api/deleteUserById/5
GOOD (Noun-based REST URLs):
-
GET /api/users(Get all users)
-
POST /api/users(Create a new user)
-
DELETE /api/users/5(Delete user #5)
*Notice how the URL never changes for Create and Read. Only the HTTP Method changes.*
5. Naming Conventions
To ensure consistency across the industry, adhere strictly to these conventions:-
1.
Use Plural Nouns: Always use plurals. Use
/api/users, never/api/user. Use/api/products, never/api/product.
-
2.
Use Kebab-Case: If a resource name has two words, separate them with a hyphen. Use
/api/support-tickets, never/api/supportTicketsor/api/supporttickets.
-
3.
Keep URLs Lowercase: URLs are case-sensitive on Linux servers. Always stick to lowercase to prevent
404 Not Founderrors.
6. Collections vs. Single Resources
REST APIs deal with two primary scopes:- The Collection: The entire list of items.
GET /api/articles (Returns an array of 100 articles).
- The Singleton: A specific item inside the collection. To access it, append its unique Database ID (the Path Parameter) to the URL.
GET /api/articles/42 (Returns exactly one article object, ID #42).
7. Nested Resources (Relationships)
What if resources belong to other resources? (e.g., A blog post has many comments). We represent this relationship hierarchically in the URL, moving from broad to specific.Pattern: /api/parent-resource/{id}/child-resource
Examples:
-
GET /api/users/9/orders-> Get all orders belonging to User #9.
-
POST /api/articles/42/comments-> Create a new comment specifically attached to Article #42.
-
GET /api/articles/42/comments/5-> Get specific comment #5, belonging to Article #42.
*Warning:* Do not nest deeper than two levels! /api/users/9/orders/3/items/5/reviews is an unreadable nightmare. Once you have the specific ID of a resource, access it directly at the root: GET /api/items/5/reviews.
8. Path Parameters vs. Query Parameters
How do you pass extra information to the URL?- 1. Path Parameters (Identify a Resource): These are built into the URL structure to identify *which* specific item you want.
-
GET /api/users/42(42 is the Path Parameter).
-
2.
Query Parameters (Filter a Resource): Added to the end of a URL after a
?. These do not change the resource; they filter, sort, or paginate the collection.
-
GET /api/users?role=admin&age=25(Return all users, but filter only the 25-year-old admins).
9. Best Practices
-
Versioning in the URL: Always start your API with a version number (e.g.,
/api/v1/users). If you make breaking changes to your database next year, you can build/api/v2/userswithout destroying the mobile apps that are still relying onv1. We will cover this deeply in Chapter 13.
10. Common Mistakes
-
Mixing Plurals and Singulars: Creating endpoints like
GET /api/usersbut then writingGET /api/user/5for the singleton. This breaks predictability. The base collection name must never change. It must remainGET /api/users/5.
11. Exercises
-
1.
Look at this endpoint:
GET /api/v1/customers/88/invoices?status=unpaid. Identify the Base Route, the Path Parameter, the Nested Resource, and the Query Parameter.
12. Coding Challenges
- Challenge: You are tasked with designing the REST API for a music streaming service. Write out the 5 optimal RESTful URL structures (including HTTP Methods) to accomplish the following: 1) Get all artists, 2) Create a new artist, 3) Get specific artist #5, 4) Get all albums belonging to artist #5, 5) Delete specific album #12.
13. MCQs with Answers
Question 1
According to standard REST API endpoint design conventions, which of the following is the correct structure for updating a specific product with ID 42?
Question 2
When designing a URL that filters a collection of resources, which URL component should be utilized?
14. Interview Questions
-
Q: Criticize the following API endpoint design:
POST /api/deletearticlebyid?id=5. How would you refactor this to adhere strictly to RESTful conventions?
- Q: Explain the design principles behind nested resources. What is the maximum recommended nesting depth, and how should a developer handle relationships that exceed this depth?
15. FAQs
Q: How do I handle actions that don't fit into CRUD (like "calculating" or "translating")? A: This is the hardest part of REST. Try to map it to a resource if possible. For translation, instead ofPOST /api/translate, think of the translation as a resource you are creating: POST /api/translations with a body { "text": "hello", "lang": "es" }. If it truly defies nouns, standard practice allows treating the verb as a sub-resource: POST /api/users/5/ban.
16. Summary
In Chapter 5, we learned the grammar of REST endpoint design. We replaced chaotic, verb-based RPC URLs with clean, predictable, noun-based resource collections (e.g.,/api/users). We standardized our nomenclature using plural nouns and kebab-case. We explored how to target individual items using Path Parameters, how to represent relationships hierarchically with Nested Resources, and how to utilize Query Parameters to filter collections without altering the core URL structure.