HTTP and REST Fundamentals: Request, Response, and DesignLesson 2.1

RESTful URL Design Best Practices

URL design, resource naming, plural nouns, nested resources, URL hierarchy, anti-patterns, kebab-case

RESTful URL Design Best Practices

URL design is one of the most visible aspects of a REST API. A well-designed URL structure is self-documenting — developers understand what a resource is and how to interact with it just by reading the URL. Poor URL design creates confusion, inconsistency, and maintenance problems.

DiagramGood vs Bad REST URL Design

IMAGE PROMPT (replace this block with your generated image):

Flat side-by-side comparison card on white background. Title: REST URL Design: Good vs Bad. Two columns. Left column header: Bad Practice with a red X icon (#ef4444 background). Right column header: Good Practice with a green check icon (#22c55e background). Each row shows a bad URL on the left and its corrected version on the right in monospace font. Row 1: Bad: GET /getUsers | Good: GET /users. Row 2: Bad: POST /createUser | Good: POST /users. Row 3: Bad: GET /getUserOrders?userId=42 | Good: GET /users/42/orders. Row 4: Bad: DELETE /deleteUser?id=5 | Good: DELETE /users/5. Row 5: Bad: GET /api/Users/GetById/42 | Good: GET /api/users/42. Row 6: Bad: POST /api/v1/searchProducts | Good: GET /api/v1/products?search=shoes. Right column entries have a very light #3A5EFF tint background (#f0f3ff). Arrows from bad to good in #3A5EFF. Clean monospace for URLs, sans-serif for headers. White outer background.

Use Nouns, Not Verbs

The most common URL design mistake is using verbs in resource paths. REST already has verbs — they are the HTTP methods. Your URLs should describe resources (nouns), not actions (verbs).

BAD:  GET /getUsers
BAD:  POST /createUser
BAD:  DELETE /deleteUser?id=42

GOOD: GET /users
GOOD: POST /users
GOOD: DELETE /users/42

Use Plural Nouns for Collections

Collections should always be plural: /users, /products, /orders. This consistency simplifies client code — developers always know a collection endpoint is the plural form of the resource name. Individual resources are accessed by appending an identifier: /users/42.

Use Kebab-Case for Multi-Word Resources

When a resource name consists of multiple words, use kebab-case (hyphens): /blog-posts, /shipping-addresses, /payment-methods. Never use camelCase or underscores in URLs. Hyphens are URL-safe and improve readability.

Model Relationships with Nested Resources

When one resource belongs to another, model the relationship in the URL hierarchy:

GET /users/42/orders        — all orders for user 42
GET /users/42/orders/7     — specific order 7 for user 42
POST /users/42/orders      — create a new order for user 42

Avoid nesting more than two levels deep. If you need deeply nested paths, consider flattening the design and using query parameters for filtering.

Keep URLs Lowercase

URLs are case-sensitive on most servers. Always use lowercase to avoid confusion: /api/users not /API/Users. Inconsistent casing leads to hard-to-find bugs and broken links.

Do Not Include File Extensions

Avoid /users.json or /users.xml. Use the Accept header for content negotiation instead. File extensions leak implementation details and make versioning harder.