URI Design Patterns for REST APIs

In this tutorial, you will learn about URI Design Patterns for REST APIs. We cover key concepts, practical examples, and best practices to help you master this topic.

URI design patterns in REST APIs establish a consistent structure for endpoint paths, using hierarchical segments for resource identification and query parameters for filtering, sorting, and pagination.

flowchart LR
  A[Base URI] --> B[/api/v1]
  B --> C[Resource /users]
  C --> D[/users/42]
  D --> E[Nested /users/42/orders]
  A --> F[Query ?status=active]
  style A fill:#e1f5fe
  style B fill:#f3e5f5
  style C fill:#c8e6c9

A well-designed URI has three parts: the base path, the resource path, and optional query parameters. The base path typically includes the API prefix and version: /api/v1/users. The resource path identifies the entity hierarchy. Query parameters provide filtering, sorting, and pagination.

Think of the base URI as the street address of an apartment building. Each resource path is like a specific apartment number. Query parameters are like instructions for which room in the apartment to look at. Together these form a complete address for any piece of data.

Use consistent casing throughout your API. URI paths typically use kebab-case: /order-items not /orderItems. Query parameters use snake_case or camelCase depending on your convention: ?page_size=20 or ?pageSize=20.

Example: Base URI Patterns

# Version in URI path
BASE = "https://api.example.com/api/v1"

# Version in subdomain
BASE = "https://v1.api.example.com"

# No version (evolve carefully)
BASE = "https://api.example.com"

Example: Resource URI Patterns

# Collection endpoint
GET    /api/v1/products

# Single resource
GET    /api/v1/products/42

# Nested resource
GET    /api/v1/categories/12/products

# Sub-resource for related data
GET    /api/v1/users/42/profile

# Action (non-CRUD)
POST   /api/v1/users/42/orders/5/cancel

Example: Query Parameter Patterns

import requests

# Filtering
response = requests.get(
    "https://api.example.com/api/v1/products",
    params={"category": "electronics", "in_stock": True}
)
print(response.url)

Expected output:

https://api.example.com/api/v1/products?category=electronics&in_stock=True

Trailing slashes should be consistent. Either always use them (/users/) or never use them (/users). Most APIs omit trailing slashes for clarity. If a trailing slash is added, you may redirect or return a 404.

Common Mistakes

1. Inconsistent trailing slash usage — Mixing /users and /users/ forces clients to handle both patterns and can cause unexpected redirects.
2. Overloading query parameters for path-level identification — Using ?user_id=42 instead of /users/42 hides the resource hierarchy.
3. Deep nesting beyond 3 levels — /a/1/b/2/c/3/d/4 creates fragile URIs that break when relationships change.
4. Case sensitivity inconsistencies — If /Users/42 works but /users/42 does not, clients will face frustrating errors.
5. Special characters in path segments — Spaces, Unicode, and symbols in URIs must be percent-encoded, complicating client code.

Practice Questions

1. What are the three parts of a well-designed REST API URI?
2. Why should versioning be included in the URI path?
3. What is the recommended maximum nesting depth for resource URIs?
4. How do query parameters differ from path parameters in REST?
5. Challenge: Design URIs for a library management system with books, authors, members, borrowing records, and fines. Show the base URI, collection endpoints, single resource endpoints, nested resources, and query parameter filtering.

FAQ

Mini Project

Design a complete URI scheme for a task management API (like Trello or Asana). Include boards, lists, cards, comments, attachments, and members. Write out 15 endpoints with proper RESTful URI patterns.

What's Next

Now learn about HTTP methods in the next lesson on REST API Design.