URL Routing Patterns

---
name: url-routing-patterns
description: "Design and implement clean RESTful URL routing patterns, handling dynamic segments, path vs query parameters, and nested routes for maintainable web APIs."
metadata:
  tags: "url-routing, restful-design, web-api, dynamic-segments, nested-routes, path-parameters, query-parameters"
  source: "https://skilldb.dev/skills/autonomous-agent-skills/url-routing-patterns"
  pack: "autonomous-agent-skills"
  category: "Autonomous Agents"
---

# URL Routing Patterns

## When to use this skill
Use when the user says things like:
- "design RESTful routes for an API"
- "structure URLs with path and query parameters"
- "create nested routes like /teams/:teamId/members"
- "validate dynamic route parameters and slugs"


You are an AI agent that designs clean, RESTful URL structures and implements routing correctly in web applications. You understand the difference between path parameters and query parameters, how to handle dynamic segments, and how to structure nested routes for maintainability.

## Philosophy

URLs are the API of the web. They should be readable, predictable, and stable. A well-designed routing system maps user intent to application behavior through URLs that make sense to both humans and machines. Routes are not just an implementation detail; they are a contract with your users and a part of your application's public interface.

## Techniques

### Design RESTful Routes
- Use nouns for resources: `/users`, `/articles`, `/orders`.
- Use HTTP methods for actions: GET to read, POST to create, PUT to replace, PATCH to update, DELETE to remove.
- Use plural nouns for collection endpoints: `/users` not `/user`.
- Nest routes to express relationships: `/users/:userId/orders`.
- Keep nesting shallow: avoid `/a/:aId/b/:bId/c/:cId/d/:dId`.

### Handle Dynamic Segments
- Use parameterized paths for resource identification: `/users/:id`.
- Validate dynamic segments (ensure IDs are valid formats) before processing.
- Handle missing or invalid parameters with appropriate error responses.
- Use slugs for human-readable URLs: `/articles/how-to-cook-pasta`.
- Support multiple identification strategies: by ID, by slug, by unique field.

### Choose Between Query and Path Parameters
- Path parameters for resource identification: `/users/123`.
- Query parameters for filtering, sorting, and pagination: `/users?role=admin&page=2`.
- Path parameters are required; query parameters are optional.
- Use query parameters for non-hierarchical data.
- Keep query parameter names consistent across endpoints.

### Implement Nested Routes
- Express parent-child relationships through nesting: `/teams/:teamId/members`.
- Share layout components across nested routes.
- Pass parent context to child routes.
- Allow direct access to child routes when the parent is inferable.
- Use breadcrumb navigation that mirrors route nesting.

### Configure Route Guards
- Protect routes that require authentication.
- Redirect unauthenticated users to login with a return URL.
- Check authorization (permissions) after authentication.
- Guard routes on both client and server for security.
- Show appropriate feedback when access is denied.

### Implement Lazy Loading Routes
- Split code by route to reduce initial bundle size.
- Load route components on demand when the user navigates.
- Show loading indicators during chunk loading.
- Prefetch likely-next routes on hover or idle time.
- Handle chunk loading failures gracefully with retry.

### Handle 404 and Redirects
- Provide a catch-all 404 route at the end of the route list.
- Show helpful 404 pages with navigation options.
- Implement redirects for moved or renamed routes.
- Use 301 for permanent redirects, 302 for temporary.
- Log 404 hits to identify broken links or missing routes.

## Best Practices

1. Keep URLs lowercase with hyphens, not underscores or camelCase.
2. Do not expose implementation details in URLs (no `.php`, `.aspx` extensions).
3. Version APIs in the URL path (`/v1/users`) or via headers.
4. Support trailing slash and non-trailing slash consistently.
5. Use route-based code splitting to improve initial load performance.
6. Document all routes and their expected parameters.
7. Test routing with edge cases: empty parameters, special characters, very long URLs.

## Anti-Patterns

- **Verb-based routes**: Using `/getUser/123` instead of `GET /users/123`.
- **Deep nesting**: Routes like `/a/1/b/2/c/3/d/4` that are hard to read and maintain.
- **Inconsistent pluralization**: Mixing `/user/123` and `/orders/456` in the same API.
- **Route parameter overload**: Packing too many parameters into the URL path.
- **Missing 404 handling**: Letting unmatched routes show a blank page or generic error.
- **Client-only route guards**: Protecting routes only on the client, allowing direct URL access to bypass security.
- **Fragile route ordering**: Route matches depending on definition order without clear documentation.
- **Exposing internal IDs**: Using auto-increment database IDs in URLs, leaking information about data volume.