# Good - Plural nounsGET /api/users
GET /api/orders
GET /api/products
# Bad - Verbs or mixed conventionsGET /api/getUser
GET /api/user (inconsistent singular)
POST /api/createOrder
Nested Resources
# Shallow nesting (preferred)
GET /api/users/{id}/orders
GET /api/orders/{id}
# Deep nesting (avoid)
GET /api/users/{id}/orders/{orderId}/items/{itemId}/reviews
# Better:
GET /api/order-items/{id}/reviews
HTTP Methods and Status Codes
GET - Retrieve Resources
GET /api/users → 200 OK (with list)
GET /api/users/{id} → 200 OK or 404 Not Found
GET /api/users?page=2 → 200 OK (paginated)
DELETE /api/users/{id}
→ 204No Content (deleted)
→ 404NotFound
→ 409Conflict (can't delete due to references)
Filtering, Sorting, and Searching
Query Parameters
# FilteringGET /api/users?status=active
GET /api/users?role=admin&status=active
# SortingGET /api/users?sort=created_at
GET /api/users?sort=-created_at (descending)
GET /api/users?sort=name,created_at
# SearchingGET /api/users?search=john
GET /api/users?q=john
# Field selection (sparse fieldsets)GET /api/users?fields=id,name,email
from fastapi import FastAPI
app = FastAPI(
title="My API",
description="API for managing users",
version="1.0.0",
docs_url="/docs",
redoc_url="/redoc"
)
@app.get("/api/users/{user_id}",
summary="Get user by ID",
response_description="User details",
tags=["Users"]
)asyncdefget_user(
user_id: str = Path(..., description="The user ID")
):
"""
Retrieve user by ID.
Returns full user profile including:
- Basic information
- Contact details
- Account status
"""pass