| name | api-design |
| description | RESTful API patterns, request/response formatting, authentication flows, versioning. Use when: designing API endpoints, planning request bodies, structuring error responses, implementing authentication. |
| argument-hint | endpoint-path, http-method, request-schema |
API Design
When to Use
- Designing API endpoints for new features
- Planning request and response formats
- Structuring error handling responses
- Implementing authentication flows
- Versioning API changes
- Documenting API contracts
What This Skill Does
Establishes CampusOS REST API design patterns, request/response conventions, authentication requirements, HTTP status codes, and versioning strategy.
Procedure
Phase 1: Endpoint Planning
- Identify resource (e.g.,
/activities, /submissions, /users)
- Define standard HTTP methods:
- GET /resource - List all
- GET /resource/:id - Get single
- POST /resource - Create
- PATCH /resource/:id - Update
- DELETE /resource/:id - Delete
- Prefix with version:
/api/v1/activities
- Use plural nouns:
/activities not /activity
Phase 2: Request Schema
- Define request body shape (JSON)
- Specify required vs optional fields
- Include data types and constraints:
- Strings: min/max length, format
- Numbers: min/max values
- Dates: ISO 8601 format
- Enums: allowed values
- Document query parameters for filtering/pagination
Phase 3: Response Format
- Standardize response structure:
{
"status": "success|error",
"data": { ... },
"meta": { "total": 100, "page": 1, "limit": 10 }
}
- Include HTTP metadata headers:
Content-Type: application/json
X-Total-Count: 100 (for pagination)
- Wrap single objects and arrays consistently
Phase 4: Error Handling
- Use appropriate HTTP status codes:
- 200 OK - Success
- 201 Created - Resource created
- 400 Bad Request - Invalid input
- 401 Unauthorized - Missing/invalid auth
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource not found
- 500 Internal Server Error
- Include error response format:
{
"status": "error",
"code": "VALIDATION_ERROR",
"message": "Invalid request",
"details": [{ "field": "email", "message": "Invalid format" }]
}
Phase 5: Authentication
- Use Bearer tokens in Authorization header:
Authorization: Bearer <token>
- Validate token on protected endpoints
- Return 401 for missing/invalid tokens
- Include user context in request (
req.user)
- Document which endpoints require authentication
Phase 6: Pagination & Filtering
- Query parameters:
?page=1&limit=10&sort=created_at&order=desc
- Return metadata:
meta: { total, page, limit, hasMore }
- Support common filters: status, role, date range
- Validate limit range (max 100)
Quick Reference
curl -X GET http://localhost:3000/api/v1/activities \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json"
curl -X POST http://localhost:3000/api/v1/activities \
-H "Content-Type: application/json" \
-d '{"name":"Activity 1","description":"..."}'
Common Issues
| Issue | Solution |
|---|
| 400 Bad Request | Check request body schema, verify required fields present |
| 401 Unauthorized | Verify token format and validity, check Authorization header |
| 403 Forbidden | Check user permissions/role, verify resource ownership |
| Inconsistent response format | Standardize all responses with status/data/meta structure |
| Missing pagination | Add limit/offset to list endpoints, return total count |
| No error details | Include code and details array in error responses |
| Missing API documentation | Document in OpenAPI/Swagger spec alongside code |