> For the complete documentation index, see [llms.txt](https://www.pranaypourkar.co.in/the-programmers-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pranaypourkar.co.in/the-programmers-guide/api/naming-guidelines/api-endpoint-naming.md). # API Endpoint Naming ## About API endpoint naming refers to the **structured approach** of defining resource paths in an API so that they are **predictable, meaningful, and easy to understand**.\ Well-named endpoints follow **RESTful principles** (if applicable) and communicate intent through **nouns** representing resources, not verbs representing actions. Endpoints are often the **first touchpoint** between API consumers and our system. Poorly named endpoints lead to: * Higher onboarding time * Increased reliance on documentation * Risk of breaking changes during refactoring A consistent endpoint naming strategy ensures **clarity, scalability, and long-term maintainability**. ## Core Principles ### **1. Use Nouns for Resources, Not Verbs** Endpoints represent **resources** (things) rather than **actions**. **Bad:** ``` GET /getUserDetails POST /createUser DELETE /removeUser ``` Problems: * Redundant verbs duplicate HTTP method meaning. * Harder to maintain if actions expand (e.g., `updateUserDetails`). **Good:** ``` GET /users/{id} # Retrieve user details POST /users # Create new user DELETE /users/{id} # Delete user ``` Reasoning: The HTTP method (GET, POST, DELETE) already implies the action; the path should just identify the resource. ### **2. Use Lowercase and Hyphen-Separated Words** * URLs are **case-sensitive** in many systems. * Lowercase avoids confusion. * Hyphens improve readability compared to underscores. **Bad:** ``` /UserProfiles /user_profiles ``` **Good:** ``` /user-profiles ``` Reasoning: Hyphens are more natural for reading multi-word segments and are standard in most API guidelines. ### **3. Use Plural for Collections** Collections (lists of resources) should be plural, individual resources singular via ID. **Bad:** ``` GET /user # Is this one user or many? GET /order-list # Custom naming, not predictable ``` **Good:** ``` GET /users # List of users GET /users/{id} # Single user GET /orders # List of orders ``` Reasoning: Pluralization clarifies that the endpoint is a collection, and keeps it consistent across entities. ### **4. Follow Hierarchical Relationships** If a resource only exists in the context of another, make it a sub-resource. **Bad:** ``` GET /orders-items # Not clear which order GET /items?orderId=123 # Breaks natural hierarchy ``` **Good:** ``` GET /orders/{orderId}/items ``` Reasoning: Nested paths express ownership and dependency in a human-readable way. ### **5. Avoid Verb Actions in Path** If an operation is not CRUD but still a valid action, model it as a **sub-resource** or **action keyword**, not a verb on the main path. **Bad:** ``` POST /approveOrder POST /cancelInvoice ``` **Good:** ``` POST /orders/{id}/approval POST /invoices/{id}/cancellation ``` Reasoning: Keeps paths consistent; special actions look like part of the resource model. ### **6. Keep Endpoints Predictable** Similar resource types should follow the same structure everywhere. **Bad:** ``` GET /users/{id}/transactions GET /merchants/{id}/sales ``` Reasoning: Mixing naming (`transactions` vs. `sales`) makes it harder to guess endpoints. **Good:** ``` GET /users/{id}/transactions GET /merchants/{id}/transactions ``` Reasoning: Consistent naming improves discoverability and reduces documentation lookup. ### **7. Avoid Redundancy** Don’t repeat resource names unnecessarily. **Bad:** ``` /users/{userId}/user-orders ``` **Good:** ``` /users/{userId}/orders ``` Reasoning: Redundancy clutters the path and adds no new meaning. ### **8. Use Query Parameters for Filtering, Sorting, Pagination** Filters, sorts, and pagination parameters **belong in the query string**, not the path. **Bad:** ``` GET /users/active/sort/name GET /orders/pending/page/2 ``` **Good:** ``` GET /users?status=active&sort=name GET /orders?status=pending&page=2 ``` Reasoning: Path segments should identify a resource; query parameters define **how** we want it. ### **9. Keep Versioning Consistent (If in URL)** If we use URL-based versioning, keep it at the **root** and apply consistently. **Bad:** ``` /users/v1 /v1/orders/v2 ``` **Good:** ``` /v1/users /v1/orders ``` Reasoning: Mixing version positions creates confusion and migration pain. ### **10. Plan for Special Actions Carefully** Some operations don’t fit CRUD - use **clear action nouns**. **Bad:** ``` POST /resetPassword ``` **Good:** ``` POST /users/{id}/reset-password ``` Reasoning: Ties the action to the resource, making context explicit. ## **Example: E-Commerce API** ``` GET /products # List products POST /products # Create product GET /products/{id} # Get product PUT /products/{id} # Update product DELETE /products/{id} # Delete product GET /products/{id}/reviews # Reviews for a product POST /products/{id}/reviews # Add a review GET /orders # List orders POST /orders # Create order GET /orders/{id} # Get order POST /orders/{id}/cancellation # Cancel order GET /users/{id}/orders # Orders by a user ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://www.pranaypourkar.co.in/the-programmers-guide/api/naming-guidelines/api-endpoint-naming.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.