Initial commit

skills/api-design-standards/checklists/api-design-checklist.md

@@ -0,0 +1,118 @@
+# API Design Checklist
+
+**Use this checklist before creating PR for new API endpoints.**
+
+## RESTful Design
+
+- [ ] URLs use plural nouns (`/users` not `/user`)
+- [ ] URLs use lowercase with hyphens (`/user-profiles` not `/userProfiles`)
+- [ ] No verbs in URLs (`/users` not `/getUsers`)
+- [ ] Hierarchical resources follow pattern `/parent/{id}/child`
+- [ ] HTTP verbs used correctly (GET=read, POST=create, PUT=update, DELETE=delete)
+
+## Multi-Tenant Isolation
+
+- [ ] All queries filtered by `tenant_id` from JWT
+- [ ] Repository pattern used with automatic tenant filtering
+- [ ] No direct database queries bypassing repository
+- [ ] Cross-tenant access blocked (except superuser endpoints)
+- [ ] Test cases verify tenant isolation
+
+## Request/Response Schemas
+
+- [ ] Pydantic schemas defined for all requests
+- [ ] Pydantic schemas defined for all responses
+- [ ] Password hashes never returned in responses
+- [ ] Sensitive fields excluded from public schemas
+- [ ] Validation rules enforced (min/max length, format, etc.)
+- [ ] Field-level validation implemented where needed
+- [ ] Model-level validation for cross-field rules
+
+## HTTP Status Codes
+
+- [ ] 200 OK for successful GET/PUT/PATCH
+- [ ] 201 Created for successful POST
+- [ ] 204 No Content for successful DELETE
+- [ ] 400 Bad Request for invalid data
+- [ ] 401 Unauthorized for missing/invalid auth
+- [ ] 403 Forbidden for insufficient permissions
+- [ ] 404 Not Found for missing resources
+- [ ] 409 Conflict for duplicates
+- [ ] 422 Validation Error for schema failures
+
+## Error Handling
+
+- [ ] Consistent error response format (`error`, `status_code`, `detail`)
+- [ ] Custom exception handlers registered
+- [ ] Validation errors return field-level details
+- [ ] Integrity errors handled gracefully (409 Conflict)
+- [ ] Generic exceptions caught and logged
+
+## Pagination
+
+- [ ] List endpoints support pagination (`skip`, `limit`)
+- [ ] Maximum limit enforced (100 default)
+- [ ] Paginated response includes `total`, `has_more`
+- [ ] Cursor-based pagination for large datasets
+- [ ] Pagination tested with edge cases
+
+## Authentication
+
+- [ ] JWT authentication required on protected endpoints
+- [ ] `tenant_id` extracted from JWT claims
+- [ ] Superuser flag checked for admin endpoints
+- [ ] Public endpoints explicitly marked (no auth)
+- [ ] Authentication tested in integration tests
+
+## OpenAPI Documentation
+
+- [ ] Endpoint docstrings describe purpose
+- [ ] All parameters documented
+- [ ] Response schemas documented
+- [ ] Error responses documented (409, 422, etc.)
+- [ ] Examples provided for complex schemas
+- [ ] Tags assigned for logical grouping
+
+## Rate Limiting
+
+- [ ] Public endpoints have rate limiting
+- [ ] Critical endpoints (create, update) have stricter limits
+- [ ] Rate limit uses Upstash Redis
+- [ ] Rate limit headers included in response
+
+## Testing
+
+- [ ] Unit tests for repository methods
+- [ ] Integration tests for all CRUD operations
+- [ ] Tenant isolation verified in tests
+- [ ] Duplicate detection tested (409 Conflict)
+- [ ] Validation errors tested (422 Unprocessable)
+- [ ] Authentication tested (401 Unauthorized)
+- [ ] Tests run with Doppler (`doppler run --config test`)
+
+## Security
+
+- [ ] No SQL injection vulnerabilities (using ORM)
+- [ ] No hardcoded secrets or credentials
+- [ ] CORS origins from Doppler (not hardcoded)
+- [ ] Input validation on all fields
+- [ ] Output encoding prevents XSS
+- [ ] Rate limiting protects against abuse
+
+## Performance
+
+- [ ] Database queries use indexes
+- [ ] N+1 queries avoided
+- [ ] Pagination prevents loading all records
+- [ ] Heavy operations use background jobs
+- [ ] Caching implemented where appropriate
+
+## Before Merging
+
+- [ ] All tests pass (`pytest`)
+- [ ] Coverage >80% for new code
+- [ ] OpenAPI docs reviewed at `/docs`
+- [ ] Tested locally with Doppler
+- [ ] Code reviewed by teammate
+- [ ] No console.log or debug prints
+- [ ] Migration created if schema changed