Resource Naming and URL Design

Good URL design is central to a usable REST API. Use plural nouns for collections (/users, /articles), not verbs (/getUsers, /createArticle). Hierarchy expresses ownership: /users/42/posts shows the posts belonging to user 42. Keep URLs lowercase and use hyphens rather than underscores for readability. Avoid deep nesting beyond two levels. If you need /users/42/posts/7/comments/3/likes, consider flattening to /comments/3/likes or /likes?commentId=3. Query strings are appropriate for filtering, sorting, and pagination—not for resource identification.

Example

# ----- Good URL design -----

# Collections (plural nouns)
GET  /products              # list all products
POST /products              # create a product

# Single resources (noun + id)
GET    /products/99         # get product 99
PUT    /products/99         # replace product 99
PATCH  /products/99         # partial update
DELETE /products/99         # delete

# Nested resources (max 2 levels)
GET  /users/7/orders        # orders for user 7
GET  /users/7/orders/12     # specific order

# Filtering, sorting, pagination via query string
GET  /products?category=shoes&maxPrice=100
GET  /products?sort=price&order=asc
GET  /products?page=2&limit=20
GET  /products?cursor=eyJpZCI6NTB9&limit=20

# Search
GET  /search?q=running+shoes&type=product

# ----- Anti-patterns to avoid -----
# GET  /getProducts          <- verb in URL
# POST /products/delete/99   <- wrong method
# GET  /users/7/posts/3/comments/9/likes/1   <- too deep
# GET  /api/v1/get_user_data?user_id=7       <- snake_case + verb

HTML

Full Editor

Related Resources

REST API Reference

Complete tag & property list

REST API How-To Guides

Step-by-step practical guides

REST API Exercises

Practice what you've learned