API Design Guidelines
REST Conventions
- Use plural nouns for resources:
/users, /posts, /comments
- Use HTTP methods correctly: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
- Nest sub-resources:
/users/:id/posts
- Use query params for filtering:
/posts?status=published&author=123
- Return proper status codes: 200, 201, 204, 400, 401, 403, 404, 409, 422, 500
Response Shape
{
"data": {},
"error": null,
"meta": { "page": 1, "total": 42 }
}
Error Response
{
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable message",
"details": [{ "field": "email", "message": "Invalid format" }]
}
}
Input Validation
- Validate all input at the API boundary
- Return 422 with field-level error details for validation failures
- Sanitize strings to prevent injection
- Enforce size limits on all inputs
Authentication
- Use the project's existing auth mechanism
- Apply auth middleware at the router level
- Return 401 for missing/invalid credentials
- Return 403 for insufficient permissions
Versioning
- Follow the project's existing versioning strategy
- If none exists, prefer URL path versioning:
/api/v1/resource
1---2name: api-design3description: API design guidelines for the fullstack-dev team4---5
6# API Design Guidelines
7
8## REST Conventions
9- Use plural nouns for resources: `/users`, `/posts`, `/comments`
10- Use HTTP methods correctly: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
11- Nest sub-resources: `/users/:id/posts`
12- Use query params for filtering: `/posts?status=published&author=123`
13- Return proper status codes: 200, 201, 204, 400, 401, 403, 404, 409, 422, 500
14
15## Response Shape
16```json
17{
18 "data": {},
19 "error": null,
20 "meta": { "page": 1, "total": 42 }
21}
22```
23
24## Error Response
25```json
26{
27 "data": null,
28 "error": {
29 "code": "VALIDATION_ERROR",
30 "message": "Human-readable message",
31 "details": [{ "field": "email", "message": "Invalid format" }]
32 }
33}
34```
35
36## Input Validation
37- Validate all input at the API boundary
38- Return 422 with field-level error details for validation failures
39- Sanitize strings to prevent injection
40- Enforce size limits on all inputs
41
42## Authentication
43- Use the project's existing auth mechanism
44- Apply auth middleware at the router level
45- Return 401 for missing/invalid credentials
46- Return 403 for insufficient permissions
47
48## Versioning
49- Follow the project's existing versioning strategy
50- If none exists, prefer URL path versioning: `/api/v1/resource`
monumentalsystems