APIbasic

RESTful Resource Naming

The practice of naming API endpoints using plural nouns and hierarchical paths to represent resources and their relationships.

Also known as: REST URL Design, Resource URI Patterns

Description

RESTful resource naming is the discipline of structuring URL paths so they clearly communicate what resource is being acted upon and how resources relate to one another. The core principle is to use plural nouns -- /users, /orders, /products -- rather than verbs, because the HTTP method already conveys the action. Sub-resources express ownership or containment: /users/{userId}/addresses/{addressId} tells the consumer that addresses belong to users.

Good resource naming avoids deeply nested hierarchies (generally no more than two levels) and uses consistent casing -- kebab-case for URL paths and camelCase or snake_case for query parameters and JSON fields, depending on the ecosystem's conventions. Actions that don't map cleanly to CRUD can be modeled as sub-resources (e.g., POST /orders/{id}/cancellation) or as a dedicated action endpoint when pragmatism demands it.

Consistent naming directly impacts developer experience and API discoverability. When resource names are predictable, consumers can guess endpoints without constantly referencing documentation. This reduces support burden and accelerates integration timelines.

Prompt Snippet

Use plural kebab-case nouns for all resource paths: /api/v1/line-items, not /api/v1/lineItem or /api/v1/line_items. Limit nesting to two levels (/users/{userId}/orders) and provide top-level collection endpoints with filter params for deeper access (/orders?userId=abc). Model non-CRUD actions as sub-resource POSTs (e.g., POST /orders/{id}/cancellations) rather than verb-based URLs. Document all resource naming conventions in the API style guide and enforce via OpenAPI path linting.