Restful Uri Design

title: "RESTful URI Design — Resource Naming Conventions for REST APIs" description: "RESTful URI design uses plural nouns for resources, hierarchical paths for relationships, and consistent naming conventions for predictable and intuitive URLs." date: 2026-06-28 lastmod: 2026-06-28 weight: 11 tags: [apis, restful] }

RESTful URI design uses plural nouns, hierarchical paths, and consistent conventions to create predictable, intuitive resource URLs that scale with your API.

What You'll Learn

• Resource naming conventions
• URI hierarchy and relationships
• Query parameter conventions

Why It Matters

Well-designed URIs make your API intuitive. Developers should predict endpoint URLs without consulting documentation.

URI Design Patterns

Code Examples

# Good URI design
# Collections: plural nouns
GET    /users
POST   /users
GET    /users/{id}
PUT    /users/{id}
DELETE /users/{id}

# Relationships: nested resources
GET    /users/{id}/orders
GET    /users/{id}/orders/{order_id}

# Filters: query parameters
GET    /users?status=active&role=admin
GET    /users?page=2&per_page=20

# Actions: for non-CRUD operations
POST   /users/{id}/activate
POST   /orders/{id}/cancel

# Bad URI design
GET    /getUsers         # Verb in URL
POST   /createUser       # Verb in URL
GET    /user             # Singular
GET    /users/42/ord     # Abbreviated
POST   /users/update/42  # Verb + inconsistent

// Express with RESTful URIs
app.get('/api/users', listUsers);
app.post('/api/users', createUser);
app.get('/api/users/:id', getUser);
app.put('/api/users/:id', updateUser);
app.delete('/api/users/:id', deleteUser);

// Nested routes
app.get('/api/users/:userId/orders', listUserOrders);
app.post('/api/users/:userId/orders', createUserOrder);

// Filter and pagination
app.get('/api/users', (req, res) => {
  const { status, role, page = 1, limit = 20 } = req.query;
  // ...
});

Common Mistakes

1. Verbs in URLs

Use HTTP methods, not verbs. /getUsers should be GET /users.

2. Inconsistent Pluralization

Some /user, others /users. Standardize on plurals.

3. CamelCase vs kebab-case

Pick one: /userOrders or /user-orders. kebab-case is preferred.

4. Over-Nesting

Avoid deeply nested URIs: /a/b/c/d/e. Flatten with query params.

5. File Extensions in URIs

/users.json and /users.xml should use content negotiation instead.

Practice Questions

1. Should resource URIs use plural or singular nouns?
2. Where do verbs belong in RESTful design?
3. How deep should URI nesting go?
4. What is the preferred casing for URI segments?
5. How do you handle non-CRUD operations in URIs?

Answers:

1. Plural nouns (/users, /orders).
2. Verbs are not in URIs. Use HTTP methods instead.
3. Max 2-3 levels deep. Use query parameters for further filtering.
4. kebab-case (/user-orders).
5. Use POST with action endpoints (/users/{id}/activate).

Challenge: Redesign a poorly structured API with verbs, singular nouns, and inconsistent naming into proper RESTful URIs. Document before and after.

FAQ