gh-greyhaven-ai-claude-code-config-grey-haven-plugins-developer-experience/skills/api-design-standards/checklists/api-design-checklist.md

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