.cursorrules (deprecated)

1# REST API Design — Cursor Rules
2# Comprehensive rules for designing and implementing RESTful APIs
3 
4## Project Context
5You are designing or maintaining a RESTful API. The API should follow REST principles,
6use standard HTTP semantics, and provide a consistent, predictable interface for clients.
7The API is versioned, documented, and designed for both internal and external consumption.
8 
9## Design Principles
10- Resources are nouns, actions are HTTP methods
11- Consistent and predictable URL patterns
12- Standard HTTP status codes
13- Meaningful error responses
14- Pagination on all collection endpoints
15- Versioning from day one
16- HATEOAS where practical (links to related resources)
17 
18## URL Design
19 
20### Naming Conventions
21- Use plural nouns for resources: `/users`, `/orders`, `/products`
22- Use kebab-case for multi-word resources: `/order-items`, `/user-profiles`
23- Use path parameters for identity: `/users/{id}`, `/orders/{orderId}/items/{itemId}`
24- Use query parameters for filtering, sorting, pagination
25- Nest resources for clear ownership: `/users/{id}/orders` (orders belonging to a user)
26- Maximum nesting depth: 2 levels (e.g., `/users/{id}/orders/{orderId}`)
27 
28### URL Patterns
29```
30GET    /api/v1/users              # List users (with pagination)
31POST   /api/v1/users              # Create a user
32GET    /api/v1/users/{id}         # Get a specific user
33PUT    /api/v1/users/{id}         # Full update of a user
34PATCH  /api/v1/users/{id}         # Partial update of a user
35DELETE /api/v1/users/{id}         # Delete a user
36 
37GET    /api/v1/users/{id}/orders  # List orders for a user
38POST   /api/v1/users/{id}/orders  # Create an order for a user
39 
40# Filtering, sorting, pagination via query params
41GET    /api/v1/orders?status=pending&sort=-created_at&page=2&limit=20
42 
43# Search as a sub-resource or query param
44GET    /api/v1/products/search?q=laptop&category=electronics
45 
46# Actions that don't map to CRUD — use verbs as sub-resources
47POST   /api/v1/orders/{id}/cancel
48POST   /api/v1/users/{id}/verify-email
49```
50 
51### What to Avoid
52- Verbs in URLs: `/getUsers`, `/createOrder` (use HTTP methods instead)
53- Singular resource names: `/user` instead of `/users`
54- Deeply nested URLs: `/api/users/{id}/orders/{oid}/items/{iid}/reviews`
55- File extensions: `/api/users.json` (use Accept header)
56- Query parameters for resource identity: `/api/users?id=123`
57 
58## HTTP Methods
59 
60### Semantic Usage
61| Method | Purpose | Idempotent | Safe | Request Body |
62|--------|---------|------------|------|-------------|
63| GET    | Read resource(s) | Yes | Yes | No |
64| POST   | Create resource / trigger action | No | No | Yes |
65| PUT    | Full resource replacement | Yes | No | Yes |
66| PATCH  | Partial resource update | No* | No | Yes |
67| DELETE | Remove a resource | Yes | No | Optional |
68 
69### Rules
70- GET must never modify server state
71- POST for creation returns 201 with Location header
72- PUT replaces the entire resource — omitted fields are reset
73- PATCH updates only the provided fields
74- DELETE returns 204 (no content) on success
75- Use POST for actions that don't map to CRUD
76 
77## Request and Response Format
78 
79### Request Bodies
80```json
81// POST /api/v1/users
82{
83  "email": "alice@example.com",
84  "name": "Alice Johnson",
85  "role": "admin"
86}
87 
88// PATCH /api/v1/users/123 (only updated fields)
89{
90  "name": "Alice Smith"
91}
92```
93 
94### Successful Responses
95```json
96// Single resource (GET /api/v1/users/123)
97{
98  "data": {
99    "id": "123",
100    "email": "alice@example.com",
101    "name": "Alice Johnson",
102    "role": "admin",
103    "createdAt": "2025-01-15T10:30:00Z"
104  }
105}
106 
107// Collection (GET /api/v1/users?page=2&limit=20)
108{
109  "data": [
110    { "id": "123", "email": "alice@example.com", "name": "Alice Johnson" },
111    { "id": "124", "email": "bob@example.com", "name": "Bob Smith" }
112  ],
113  "meta": {
114    "page": 2,
115    "limit": 20,
116    "total": 156,
117    "totalPages": 8
118  }
119}
120 
121// Created resource (POST /api/v1/users — 201)
122{
123  "data": {
124    "id": "125",
125    "email": "carol@example.com",
126    "name": "Carol Davis"
127  }
128}
129// Headers: Location: /api/v1/users/125
130```
131 
132### Error Responses
133```json
134// 400 Bad Request (validation error)
135{
136  "error": {
137    "code": "VALIDATION_ERROR",
138    "message": "Invalid request data",
139    "details": [
140      { "field": "email", "message": "Must be a valid email address" },
141      { "field": "name", "message": "Must be between 1 and 100 characters" }
142    ]
143  }
144}
145 
146// 404 Not Found
147{
148  "error": {
149    "code": "NOT_FOUND",
150    "message": "User with ID 999 not found"
151  }
152}
153 
154// 409 Conflict
155{
156  "error": {
157    "code": "CONFLICT",
158    "message": "A user with this email already exists"
159  }
160}
161```
162 
163## Status Codes
164 
165### Use Correctly
166- **200** OK — Successful GET, PUT, PATCH, or DELETE
167- **201** Created — Successful POST that creates a resource
168- **204** No Content — Successful DELETE or update with no response body
169- **400** Bad Request — Invalid input, validation failure
170- **401** Unauthorized — Missing or invalid authentication
171- **403** Forbidden — Authenticated but not authorized for this resource
172- **404** Not Found — Resource does not exist
173- **409** Conflict — Duplicate resource or state conflict
174- **422** Unprocessable Entity — Valid JSON but semantically incorrect
175- **429** Too Many Requests — Rate limit exceeded
176- **500** Internal Server Error — Unexpected server failure
177 
178## Pagination
179 
180### Cursor-Based (Preferred for Large Datasets)
181```
182GET /api/v1/orders?limit=20&after=eyJpZCI6MTIzfQ
183```
184```json
185{
186  "data": [...],
187  "meta": {
188    "hasMore": true,
189    "cursors": {
190      "after": "eyJpZCI6MTQzfQ",
191      "before": "eyJpZCI6MTI0fQ"
192    }
193  }
194}
195```
196 
197### Offset-Based (Simpler but Slower on Large Data)
198```
199GET /api/v1/products?page=3&limit=20
200```
201 
202## Filtering and Sorting
203```
204GET /api/v1/orders?status=pending,shipped&created_after=2025-01-01&sort=-created_at,total
205```
206- Comma-separated values for OR filters
207- Prefix with `-` for descending sort
208- Use descriptive parameter names, not operator syntax
209 
210## Versioning
211- Use URL path versioning: `/api/v1/`, `/api/v2/`
212- Never break existing API versions
213- Deprecate old versions with headers: `Sunset: Sat, 01 Jan 2026 00:00:00 GMT`
214- Version only when making breaking changes
215 
216## Authentication and Authorization
217- Use Bearer tokens in Authorization header: `Authorization: Bearer <token>`
218- Return 401 for missing/invalid tokens, 403 for insufficient permissions
219- Include rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`
220- Use scopes or roles for fine-grained access control
221 
222## Documentation
223- Generate OpenAPI/Swagger spec from code annotations
224- Document every endpoint with request/response examples
225- Document error codes and their meanings
226- Include authentication requirements per endpoint
227- Provide curl examples for every endpoint
228 
229## Common Pitfalls
230- Using POST for everything instead of appropriate HTTP methods
231- Returning 200 for errors (always use correct status codes)
232- Inconsistent response format between endpoints
233- Not paginating collection endpoints (returning unbounded lists)
234- Exposing internal IDs or database structure in URLs
235- Not versioning the API from the start
236- Breaking changes without a new version
237- Returning different response shapes for the same resource type
238- Not setting Content-Type headers on responses
239- Forgetting CORS headers for browser clients
240