1# REST API Best Practices
2 
3## URL Structure
4 
5### Resource Naming
6 
7```
8# Good - Plural nouns
9GET /api/users
10GET /api/orders
11GET /api/products
12 
13# Bad - Verbs or mixed conventions
14GET /api/getUser
15GET /api/user  (inconsistent singular)
16POST /api/createOrder
17```
18 
19### Nested Resources
20 
21```
22# Shallow nesting (preferred)
23GET /api/users/{id}/orders
24GET /api/orders/{id}
25 
26# Deep nesting (avoid)
27GET /api/users/{id}/orders/{orderId}/items/{itemId}/reviews
28# Better:
29GET /api/order-items/{id}/reviews
30```
31 
32## HTTP Methods and Status Codes
33 
34### GET - Retrieve Resources
35 
36```
37GET /api/users              → 200 OK (with list)
38GET /api/users/{id}         → 200 OK or 404 Not Found
39GET /api/users?page=2       → 200 OK (paginated)
40```
41 
42### POST - Create Resources
43 
44```
45POST /api/users
46  Body: {"name": "John", "email": "[email protected]"}
47  → 201 Created
48  Location: /api/users/123
49  Body: {"id": "123", "name": "John", ...}
50 
51POST /api/users (validation error)
52  → 422 Unprocessable Entity
53  Body: {"errors": [...]}
54```
55 
56### PUT - Replace Resources
57 
58```
59PUT /api/users/{id}
60  Body: {complete user object}
61  → 200 OK (updated)
62  → 404 Not Found (doesn't exist)
63 
64# Must include ALL fields
65```
66 
67### PATCH - Partial Update
68 
69```
70PATCH /api/users/{id}
71  Body: {"name": "Jane"}  (only changed fields)
72  → 200 OK
73  → 404 Not Found
74```
75 
76### DELETE - Remove Resources
77 
78```
79DELETE /api/users/{id}
80  → 204 No Content (deleted)
81  → 404 Not Found
82  → 409 Conflict (can't delete due to references)
83```
84 
85## Filtering, Sorting, and Searching
86 
87### Query Parameters
88 
89```
90# Filtering
91GET /api/users?status=active
92GET /api/users?role=admin&status=active
93 
94# Sorting
95GET /api/users?sort=created_at
96GET /api/users?sort=-created_at  (descending)
97GET /api/users?sort=name,created_at
98 
99# Searching
100GET /api/users?search=john
101GET /api/users?q=john
102 
103# Field selection (sparse fieldsets)
104GET /api/users?fields=id,name,email
105```
106 
107## Pagination Patterns
108 
109### Offset-Based Pagination
110 
111```python
112GET /api/users?page=2&page_size=20
113 
114Response:
115{
116  "items": [...],
117  "page": 2,
118  "page_size": 20,
119  "total": 150,
120  "pages": 8
121}
122```
123 
124### Cursor-Based Pagination (for large datasets)
125 
126```python
127GET /api/users?limit=20&cursor=eyJpZCI6MTIzfQ
128 
129Response:
130{
131  "items": [...],
132  "next_cursor": "eyJpZCI6MTQzfQ",
133  "has_more": true
134}
135```
136 
137### Link Header Pagination (RESTful)
138 
139```
140GET /api/users?page=2
141 
142Response Headers:
143Link: <https://api.example.com/users?page=3>; rel="next",
144      <https://api.example.com/users?page=1>; rel="prev",
145      <https://api.example.com/users?page=1>; rel="first",
146      <https://api.example.com/users?page=8>; rel="last"
147```
148 
149## Versioning Strategies
150 
151### URL Versioning (Recommended)
152 
153```
154/api/v1/users
155/api/v2/users
156 
157Pros: Clear, easy to route
158Cons: Multiple URLs for same resource
159```
160 
161### Header Versioning
162 
163```
164GET /api/users
165Accept: application/vnd.api+json; version=2
166 
167Pros: Clean URLs
168Cons: Less visible, harder to test
169```
170 
171### Query Parameter
172 
173```
174GET /api/users?version=2
175 
176Pros: Easy to test
177Cons: Optional parameter can be forgotten
178```
179 
180## Rate Limiting
181 
182### Headers
183 
184```
185X-RateLimit-Limit: 1000
186X-RateLimit-Remaining: 742
187X-RateLimit-Reset: 1640000000
188 
189Response when limited:
190429 Too Many Requests
191Retry-After: 3600
192```
193 
194### Implementation Pattern
195 
196```python
197from fastapi import HTTPException, Request
198from datetime import datetime, timedelta
199 
200class RateLimiter:
201    def __init__(self, calls: int, period: int):
202        self.calls = calls
203        self.period = period
204        self.cache = {}
205 
206    def check(self, key: str) -> bool:
207        now = datetime.now()
208        if key not in self.cache:
209            self.cache[key] = []
210 
211        # Remove old requests
212        self.cache[key] = [
213            ts for ts in self.cache[key]
214            if now - ts < timedelta(seconds=self.period)
215        ]
216 
217        if len(self.cache[key]) >= self.calls:
218            return False
219 
220        self.cache[key].append(now)
221        return True
222 
223limiter = RateLimiter(calls=100, period=60)
224 
225@app.get("/api/users")
226async def get_users(request: Request):
227    if not limiter.check(request.client.host):
228        raise HTTPException(
229            status_code=429,
230            headers={"Retry-After": "60"}
231        )
232    return {"users": [...]}
233```
234 
235## Authentication and Authorization
236 
237### Bearer Token
238 
239```
240Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
241 
242401 Unauthorized - Missing/invalid token
243403 Forbidden - Valid token, insufficient permissions
244```
245 
246### API Keys
247 
248```
249X-API-Key: your-api-key-here
250```
251 
252## Error Response Format
253 
254### Consistent Structure
255 
256```json
257{
258  "error": {
259    "code": "VALIDATION_ERROR",
260    "message": "Request validation failed",
261    "details": [
262      {
263        "field": "email",
264        "message": "Invalid email format",
265        "value": "not-an-email"
266      }
267    ],
268    "timestamp": "2025-10-16T12:00:00Z",
269    "path": "/api/users"
270  }
271}
272```
273 
274### Status Code Guidelines
275 
276- `200 OK`: Successful GET, PATCH, PUT
277- `201 Created`: Successful POST
278- `204 No Content`: Successful DELETE
279- `400 Bad Request`: Malformed request
280- `401 Unauthorized`: Authentication required
281- `403 Forbidden`: Authenticated but not authorized
282- `404 Not Found`: Resource doesn't exist
283- `409 Conflict`: State conflict (duplicate email, etc.)
284- `422 Unprocessable Entity`: Validation errors
285- `429 Too Many Requests`: Rate limited
286- `500 Internal Server Error`: Server error
287- `503 Service Unavailable`: Temporary downtime
288 
289## Caching
290 
291### Cache Headers
292 
293```
294# Client caching
295Cache-Control: public, max-age=3600
296 
297# No caching
298Cache-Control: no-cache, no-store, must-revalidate
299 
300# Conditional requests
301ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
302If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
303→ 304 Not Modified
304```
305 
306## Bulk Operations
307 
308### Batch Endpoints
309 
310```python
311POST /api/users/batch
312{
313  "items": [
314    {"name": "User1", "email": "[email protected]"},
315    {"name": "User2", "email": "[email protected]"}
316  ]
317}
318 
319Response:
320{
321  "results": [
322    {"id": "1", "status": "created"},
323    {"id": null, "status": "failed", "error": "Email already exists"}
324  ]
325}
326```
327 
328## Idempotency
329 
330### Idempotency Keys
331 
332```
333POST /api/orders
334Idempotency-Key: unique-key-123
335 
336If duplicate request:
337→ 200 OK (return cached response)
338```
339 
340## CORS Configuration
341 
342```python
343from fastapi.middleware.cors import CORSMiddleware
344 
345app.add_middleware(
346    CORSMiddleware,
347    allow_origins=["https://example.com"],
348    allow_credentials=True,
349    allow_methods=["*"],
350    allow_headers=["*"],
351)
352```
353 
354## Documentation with OpenAPI
355 
356```python
357from fastapi import FastAPI
358 
359app = FastAPI(
360    title="My API",
361    description="API for managing users",
362    version="1.0.0",
363    docs_url="/docs",
364    redoc_url="/redoc"
365)
366 
367@app.get(
368    "/api/users/{user_id}",
369    summary="Get user by ID",
370    response_description="User details",
371    tags=["Users"]
372)
373async def get_user(
374    user_id: str = Path(..., description="The user ID")
375):
376    """
377    Retrieve user by ID.
378 
379    Returns full user profile including:
380    - Basic information
381    - Contact details
382    - Account status
383    """
384    pass
385```
386 
387## Health and Monitoring Endpoints
388 
389```python
390@app.get("/health")
391async def health_check():
392    return {
393        "status": "healthy",
394        "version": "1.0.0",
395        "timestamp": datetime.now().isoformat()
396    }
397 
398@app.get("/health/detailed")
399async def detailed_health():
400    return {
401        "status": "healthy",
402        "checks": {
403            "database": await check_database(),
404            "redis": await check_redis(),
405            "external_api": await check_external_api()
406        }
407    }
408```
409