Resource Naming and URI Design Best Practices
What You'll Learn
You'll learn how to structure clean, predictable URIs by using nouns for resources, hierarchical paths for relationships, and consistent patterns that make your API intuitive.
The Core Idea
A well-designed URI acts like a postal address for data—it should clearly identify what you're accessing, not how you're accessing it. The HTTP method (GET, POST, PUT, DELETE) already tells you the action, so your URI should focus solely on naming the resource.
Use Nouns, Not Verbs
URIs represent things (resources), not actions. The action comes from the HTTP method.
Good:
GET /users/123(fetch user)POST /users(create user)DELETE /orders/456(delete order)
Bad:
GET /getUser/123POST /createUserDELETE /deleteOrder/456
The verb is redundant—your HTTP method already expresses it.
Hierarchical Paths for Relationships
Use path segments to represent parent-child relationships or scoped resources.
Good:
GET /users/123/orders(orders belonging to user 123)GET /users/123/orders/789(specific order for that user)
This naturally mirrors how resources nest in your domain model.
Consistent Patterns
Maintain predictable structure across your API:
- Use plural nouns for collections:
/users,/orders - Use lowercase with hyphens for readability:
/user-profiles, not/UserProfilesor/user_profiles - Keep depth shallow (typically 2-3 levels max)
Consistency Example:
/products/42/reviewsfollows the same pattern as/users/123/orders
Both use /{collection}/{id}/{sub-collection}.
Key Takeaway:
Design URIs as resource identifiers using nouns, hierarchical paths for relationships, and consistent naming patterns—the HTTP method handles the action, so your URI just needs to clearly name what you're working with.