Resources and Naming Conventions in REST API Design

In this tutorial, you will learn about Resources and Naming Conventions in REST API ilink "Api Design" >}}. We cover key concepts, practical examples, and best practices to help you master this topic.

REST resource naming conventions define how you structure URIs to represent entities in your system, using plural nouns, hierarchical paths, and consistent patterns that make your API intuitive and predictable for clients.

flowchart TD
  A[Resource Identification] --> B[Plural Nouns]
  A --> C[No Verbs]
  A --> D[Snake Case or Kebab]
  B --> E[/users/]
  B --> F[/orders/]
  C --> G[/users/42 not /getUser]
  style A fill:#e1f5fe
  style E fill:#c8e6c9
  style G fill:#ffcdd2

Choose nouns that represent the domain entities clearly. A user resource is /users, an order resource is /orders. Resources can be nested to show relationships: /users/42/orders represents orders belonging to user 42.

Think of URIs like a filesystem path. Just as you navigate /home/user/docs/report.pdf, an API client navigates /users/42/orders/5. Each segment narrows the scope. This hierarchical structure is intuitive because it mirrors how we organize information in folders.

Why plural nouns? Because /users represents a collection of users, and /users/42 represents a single member of that collection. If you used /user/42, the collection would awkwardly be /user which implies a single user. Consistency matters.

Use kebab-case for multi-word resources: /order-items not /orderItems or /order_items. HTTP headers use snake_case, but URIs typically use kebab-case for readability.

Do not use verbs in URIs. Verbs belong in HTTP methods, not URIs. Instead of /getUser/42, use GET /users/42. Instead of /deleteUser/42, use DELETE /users/42.

Example: Well-Designed Resource URIs

# Collection
GET    /users           # List all users
POST   /users           # Create a user

# Single resource
GET    /users/42        # Get user 42
PUT    /users/42        # Replace user 42
PATCH  /users/42        # Partially update user 42
DELETE /users/42        # Delete user 42

# Nested resources
GET    /users/42/orders        # List user 42's orders
POST   /users/42/orders        # Create order for user 42
GET    /users/42/orders/5      # Get order 5 for user 42

# Actions (rare, use POST for non-CRUD)
POST   /users/42/orders/5/cancel  # Non-CRUD action

Example: Poorly Designed URIs

GET  /getAllUsers          # Verb in URI
POST /createNewUser        # Verb in URI
GET  /userInfo/42          # Unclear resource name
POST /updateUserOrder/5    # Verb + unclear hierarchy
GET  /getUserOrders/42     # Verb in URI, missing resource

Example: Naming with Filters and Relationships

# Filtering with query parameters
GET  /products?category=electronics
GET  /orders?status=pending&date=2026-06-01

# Resource relationships
GET  /authors/7/books              # Books by author 7
GET  /categories/12/products       # Products in category 12
GET  /departments/engineering/employees  # Employees in engineering

Common Mistakes

1. Using verbs in URIs — PUT /updateUser should be PUT /users/{id}. The HTTP method already conveys the action.
2. Singular resource names — Using /user instead of /users creates inconsistency when listing a collection.
3. Inconsistent naming style — Mixing camelCase (/orderItems), snake_case (/order_items), and kebab-case (/order-items) confuses clients.
4. Deep nesting — /users/42/orders/5/items/12/reviews is too deep. Limit nesting to 2-3 levels; use query parameters for further refinement.
5. Ambiguous resource names — /getAllActiveUsersWithOrders is a description, not a resource. Resources are nouns like /users?active=true.

Practice Questions

1. Should you use plural or singular nouns for collection URIs?
2. Where do verbs belong in REST API design?
3. What is the maximum recommended nesting depth for resources?
4. How would you represent orders for a specific user in REST?
5. Challenge: Design a URI scheme for an e-commerce platform with products, categories, reviews, shopping carts, and checkout. Include nested resources and query parameters for filtering.

FAQ

Mini Project

Take an existing REST API (like GitHub API) and analyze its URI structure. Document 10 endpoints, noting whether they follow REST naming conventions. Identify any violations and propose corrected URIs.

What's Next

Now learn URI Design Patterns in REST API Design.