How to Document API Routes

Creating a New API Route Document

1. Create a file [route-name].md in bidscript-dev-docs/docs/frontend/api/(...any remaining appropriate sub-directories)/.

2. Use this template:

# Route Name(api/route-name.ts)

## Endpoint Overview
One-line description of the route's purpose, authentication requirements, and response format, followed by an overview of the POST/GET/PUT/DELETE handlers.

## Request Handlers
### GET/POST/PUT/DELETE
- Parameters/body
- Response structure
- Status codes

## Error Handling
Table of error codes and their descriptions. Common errors and recovery strategies.

## Usage Examples
Code snippet showing usage examples of each handler.

## Implementation Details
Code snippets showing the implementation of each handler.

## Pages/Components Referenced By
Exhaustive list of pages/components using this route with context.

## Notes
Important considerations and limitations.

3. Update the mkdocs.yml file's nav section to include your new API route documentation:

nav:
  - Frontend:
      - API Routes:
          - YourRoute: frontend/api/your-route.md

Example (from codebase)

Profile Stats (api/profileStats.ts)

Endpoint Overview

Fetches user document and request statistics for different time periods (7 days, 30 days, 24 hours).

Request Handlers

POST

• Body: { userID: string }
• Response:

  {
    documentsInLast7Days: number,
    documentsInLast30Days: number,
    documentsInLastDay: number,
    totalRequestsInLast7Days: number,
    totalRequestsInLast30Days: number,
    totalRequestsInLastDay: number
  }
  

• Status: 200 OK, 400 Bad Request, 500 Server Error

Error Handling

try {
  const profileStats = await prisma.requests.findMany({...});
} catch (error) {
  console.error('Error fetching profile stats:', error);
  res.status(500).json({ error: 'Failed to fetch profile stats' });
}

Usage Example

const response = await fetch("app/api/profileStats", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ userID })
});
const data = await response.json();

Implementation Details

• Uses Prisma for database queries
• Calculates stats using date filtering
• Aggregates request counts
• Handles multiple time periods

Pages/Components Referenced By

• Home page (pages/index.tsx) - Displays user statistics dashboard
• Profile component (components/profile.tsx) - Shows activity metrics

Notes

• Rate limited to 100 requests/minute
• Cached for 5 minutes
• Requires authentication
• Returns 0 for empty results