URI Design Best Practices
A well-designed URI structure makes your API intuitive and easy to use. Let's explore advanced URI design patterns.
URI Structure
A typical REST URI has this structure:
https://api.example.com/v1/users/123/orders?status=pending
└─────────────────────┘ └┘ └───────────────┘ └───────────┘
Base URL Ver Resource Path Query String
Resource Hierarchy
Parent-Child Relationships
Express ownership or containment through nesting:
/users/123/orders # User's orders
/orders/456/items # Order's items
/teams/789/members # Team's members
Limiting Depth
Keep nesting to 2-3 levels maximum. Deeper nesting becomes unwieldy:
# Too deep
/companies/1/departments/2/teams/3/members/4/tasks
# Better - use query parameters or separate resources
/tasks?member=4
/members/4/tasks
Handling Non-CRUD Operations
Sometimes you need endpoints that don't fit the CRUD model. Here are patterns for handling them:
1. Sub-Resource Pattern
Treat the action as a sub-resource:
POST /users/123/password-reset # Trigger password reset
POST /orders/456/cancellation # Cancel an order
POST /documents/789/pdf # Generate PDF
2. Controller Pattern
For RPC-style actions, use a verb as the last segment:
POST /cart/checkout
POST /emails/send
POST /reports/generate
3. State Transition
Use the resource state:
PATCH /orders/456
{ "status": "cancelled" }
Filtering and Search
Collection Filtering
Use query parameters for filtering collections:
/products?category=electronics
/products?category=electronics&price_min=100
/users?role=admin&status=active
Search
Use a dedicated search endpoint or query parameter:
/products/search?q=laptop
/products?q=laptop
/search?q=laptop&type=products
Practical Examples
Let's design URIs for a blog platform:
# Blog resources
GET /blogs # List all blogs
POST /blogs # Create a blog
GET /blogs/tech-daily # Get specific blog
PUT /blogs/tech-daily # Update blog
DELETE /blogs/tech-daily # Delete blog
# Posts within a blog
GET /blogs/tech-daily/posts # List blog's posts
POST /blogs/tech-daily/posts # Create post
GET /blogs/tech-daily/posts/123 # Get post
PATCH /blogs/tech-daily/posts/123 # Update post
# Comments on posts
GET /posts/123/comments # List comments
POST /posts/123/comments # Add comment
# User's data across blogs
GET /users/456/posts # User's posts
GET /users/456/comments # User's comments
Exercise: Design URIs for an E-Commerce API
URI Anti-Patterns
Don't Do This
# Verbs in URI
/api/getProductById?id=123
# Redundant information
/api/product/product-123
# Inconsistent naming
/api/Users/123
/api/product/456
/api/order_items
# Version in filename
/api/users_v2/123
# Query string for resource ID
/api/users?userId=123
Do This Instead
/api/products/123
/api/products/123
/api/users/123
/api/products/456
/api/order-items
/api/v2/users/123
/api/users/123
Summary
Good URI design follows these principles:
- Use nouns, not verbs - Let HTTP methods express actions
- Use plurals - Consistent and intuitive
- Express relationships - Through path hierarchy
- Keep it flat-ish - 2-3 levels of nesting max
- Be consistent - Same patterns throughout your API
- Make it readable - Use hyphens, lowercase
A well-designed URI is like a well-organized file system - users should be able to guess the structure without reading documentation.
التالي · الدرس 6 من 37
Resource Naming Exercises
قراءة 2 دقيقة
أنهيت 5 من 37 درسًا

اسأل Byte عن هذا الدرس
محادثة خاصة حول هذا الدرس. قرأ Byte الدرس كاملًا، ويجيب خلال ثوانٍ، ويُظهر القسم الذي تأتي منه كل إجابة. يمكنك السؤال بأي لغة.
الأسئلة والأجوبة
أسئلة عامة حول هذا الدرس. يجيب AI Tutor فورًا بلغتك، ويراجع فريق FreeAcademy الإجابات، ويمكن لكل المتعلمين قراءتها.

