API / Backend Service Template

Use this template when documenting API or backend service packages.

MANDATORY: Before using this template, analyze the current project to identify:

  1. Backend framework - Run: grep -r "express\|fastify\|koa\|nest\|hapi\|django\|flask\|gin\|fiber" package.json pyproject.toml go.mod | head -3
  2. Route organization - Run: find . -name "*route*" -o -name "*endpoint*" -o -name "*handler*" | grep -v node_modules | head -5
  3. Middleware location - Run: find . -name "*middleware*" -o -name "*auth*" | grep -v node_modules | head -5
  4. Validation approach - Run: grep -r "zod\|joi\|yup\|ajv\|pydantic" package.json pyproject.toml | head -3
  5. Error handling - Run: find . -name "*error*" -o -name "*exception*" | grep -E "\.(js|ts|py|go)$" | head -5

Adaptive Template Structure

## API Patterns
- Framework: [DETECTED_FRAMEWORK] ([Express/Fastify/Django/etc])
- Routes: `[DETECTED_ROUTES_PATH]/**/*` OR "Route organization not found"
- Auth: `[DETECTED_AUTH_PATH]` OR "Auth middleware not detected"
- Validation: [DETECTED_VALIDATION_LIB] schemas in `[SCHEMA_PATH]/**`
- Errors: `[ERROR_CLASS_NAME]` from `[ERROR_FILE_PATH]`
- Example route: `[ACTUAL_ROUTE_EXAMPLE_PATH]`

Detection Instructions

Framework-Specific Patterns

Node.js/Express: Look for app.js, server.js, route files Node.js/Fastify: Look for Fastify plugins, route definitions Node.js/NestJS: Look for controllers, decorators, modules Python/Django: Look for urls.py, views, serializers Python/Flask: Look for route decorators, blueprints Go: Look for handler functions, router setup PHP: Look for route definitions, controllers

Route Organization (Copy from Actual Project)

Before documenting, analyze how routes are actually organized:

  • Directory structure for routes/endpoints
  • HTTP method conventions in use
  • Route parameter patterns found in code
  • URL structure patterns

Middleware Stack (Detect What Exists)

Find actual middleware in use:

  • Authentication/authorization middleware files
  • Validation middleware implementations
  • Error handling middleware
  • Request logging setup (if any)

Technology-Specific Adaptations

Express.js Projects

  • Router usage patterns from existing code
  • Middleware order and setup
  • Error handling with next()

FastAPI/Django Projects

  • Dependency injection patterns
  • Serializer/Pydantic model usage
  • Authentication decorators

Go Projects

  • Handler function signatures
  • Middleware chain patterns
  • Error handling approaches

Validation Approaches (Copy from Project)

Find what’s actually implemented:

  • Schema definition location and format
  • Input validation middleware usage
  • Error response structure in use

Development Patterns (Extract from Code)

Look for existing patterns in the codebase:

  • Route testing approach (if tests exist)
  • API documentation generation (OpenAPI, etc.)
  • Request/response typing patterns

Critical Warnings (Universal)

  • NEVER expose internal error details in API responses
  • NEVER skip input validation on user inputs
  • NEVER hardcode API keys or secrets in code
  • NEVER assume framework without detection

Anti-Patterns for API Documentation

  • Don’t explain HTTP basics or REST principles
  • Don’t assume specific framework without verification
  • Don’t duplicate existing API documentation (OpenAPI/Swagger)
  • Don’t include framework tutorials - focus on project patterns
Edit this page on GitHub