designing-apis

1# Designing APIs
2 
3### When to Load
4 
5- **Trigger**: Designing REST or GraphQL endpoints, API contracts, versioning, request/response formats
6- **Skip**: Internal-only code with no API surface
7 
8## API Design Workflow
9 
10Copy this checklist and track progress:
11 
12```
13API Design Progress:
14- [ ] Step 1: Define resources and relationships
15- [ ] Step 2: Design endpoint structure
16- [ ] Step 3: Define request/response formats
17- [ ] Step 4: Plan error handling
18- [ ] Step 5: Add authentication/authorization
19- [ ] Step 6: Document with OpenAPI spec
20- [ ] Step 7: Validate design against checklist
21```
22 
23## REST API Design
24 
25### URL Structure
26 
27```
28# Resource-based URLs (nouns, not verbs)
29GET    /users              # List users
30GET    /users/:id          # Get user
31POST   /users              # Create user
32PUT    /users/:id          # Replace user
33PATCH  /users/:id          # Update user
34DELETE /users/:id          # Delete user
35 
36# Nested resources
37GET    /users/:id/orders   # User's orders
38POST   /users/:id/orders   # Create order for user
39 
40# Query parameters for filtering/pagination
41GET    /users?role=admin&status=active
42GET    /users?page=2&limit=20&sort=-createdAt
43```
44 
45### HTTP Status Codes
46 
47| Code | Meaning           | Use Case                   |
48| ---- | ----------------- | -------------------------- |
49| 200  | OK                | Successful GET, PUT, PATCH |
50| 201  | Created           | Successful POST            |
51| 204  | No Content        | Successful DELETE          |
52…