URI Design Best Practices

A well-designed URI structure makes your API intuitive and easy to use. Let's explore advanced URI design patterns.

URI Structure

A typical REST URI has this structure:

https://api.example.com/v1/users/123/orders?status=pending
└─────────────────────┘ └┘ └───────────────┘ └───────────┘
       Base URL        Ver  Resource Path    Query String

Resource Hierarchy

Parent-Child Relationships

Express ownership or containment through nesting:

/users/123/orders          # User's orders
/orders/456/items          # Order's items
/teams/789/members         # Team's members

Limiting Depth

Keep nesting to 2-3 levels maximum. Deeper nesting becomes unwieldy:

# Too deep
/companies/1/departments/2/teams/3/members/4/tasks

# Better - use query parameters or separate resources
/tasks?member=4
/members/4/tasks

Handling Non-CRUD Operations

Sometimes you need endpoints that don't fit the CRUD model. Here are patterns for handling them:

1. Sub-Resource Pattern

Treat the action as a sub-resource:

POST /users/123/password-reset     # Trigger password reset
POST /orders/456/cancellation      # Cancel an order
POST /documents/789/pdf            # Generate PDF

2. Controller Pattern

For RPC-style actions, use a verb as the last segment:

POST /cart/checkout
POST /emails/send
POST /reports/generate

3. State Transition

Use the resource state:

PATCH /orders/456
{ "status": "cancelled" }

Filtering and Search

Collection Filtering

Use query parameters for filtering collections:

/products?category=electronics
/products?category=electronics&price_min=100
/users?role=admin&status=active

Search

Use a dedicated search endpoint or query parameter:

/products/search?q=laptop
/products?q=laptop
/search?q=laptop&type=products

Practical Examples

Let's design URIs for a blog platform:

# Blog resources
GET    /blogs                    # List all blogs
POST   /blogs                    # Create a blog
GET    /blogs/tech-daily         # Get specific blog
PUT    /blogs/tech-daily         # Update blog
DELETE /blogs/tech-daily         # Delete blog

# Posts within a blog
GET    /blogs/tech-daily/posts            # List blog's posts
POST   /blogs/tech-daily/posts            # Create post
GET    /blogs/tech-daily/posts/123        # Get post
PATCH  /blogs/tech-daily/posts/123        # Update post

# Comments on posts
GET    /posts/123/comments                 # List comments
POST   /posts/123/comments                 # Add comment

# User's data across blogs
GET    /users/456/posts                    # User's posts
GET    /users/456/comments                 # User's comments

Exercise: Design URIs for an E-Commerce API

URI Anti-Patterns

Don't Do This

# Verbs in URI
/api/getProductById?id=123

# Redundant information
/api/product/product-123

# Inconsistent naming
/api/Users/123
/api/product/456
/api/order_items

# Version in filename
/api/users_v2/123

# Query string for resource ID
/api/users?userId=123

Do This Instead

/api/products/123
/api/products/123
/api/users/123
/api/products/456
/api/order-items
/api/v2/users/123
/api/users/123

Summary

Good URI design follows these principles:

1. Use nouns, not verbs - Let HTTP methods express actions
2. Use plurals - Consistent and intuitive
3. Express relationships - Through path hierarchy
4. Keep it flat-ish - 2-3 levels of nesting max
5. Be consistent - Same patterns throughout your API
6. Make it readable - Use hyphens, lowercase

A well-designed URI is like a well-organized file system - users should be able to guess the structure without reading documentation.