Course contentsShow
← System Design
Lesson 1876 of 1,91945. API Design and VersioningFree lesson

Resource Naming and URI Design Best Practices

Conventions for structuring URIs: nouns not verbs, hierarchical paths, and consistent patterns.

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/123
  • POST /createUser
  • DELETE /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 /UserProfiles or /user_profiles
  • Keep depth shallow (typically 2-3 levels max)

Consistency Example:

  • /products/42/reviews follows 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.