Overview

The API integration uses:

• Next.js server actions for backend communication
• OpenAPI schema generation with drf-spectacular
• TypeScript client generation for type safety
• Scalar for interactive API documentation

API Versioning

The API follows a versioned URL structure:

Legacy URLs (/api/schema/, /reference/) redirect to the v1 equivalents for backward compatibility.

API Documentation

Access the interactive API documentation at:

• Local: http://localhost:8000/api/v1/docs/
• Production: https://lcmd-app.epfl.ch/api/v1/docs/

The documentation is powered by Scalar and provides:

• Interactive request builder
• Code examples in multiple languages
• Schema exploration

API Client

The API client is generated using openapi-typescript-codegen and provides:

• Type-safe API calls
• Automatic authentication handling
• Centralized API configuration

Using the API Client

The getApiClient function in apps/web/lib/api.ts provides a configured client instance:

• Pre-configured authentication
• Default options set
• Error handling

Schema Management

Updating OpenAPI Schema

After backend changes (e.g., serializer updates), regenerate the TypeScript schema:

pnpm openapi:generate

In VS Code, use the built-in task for schema updates. The schema is fetched from /api/v1/schema/.

Server Actions

Server actions for API communication are located in apps/web/actions/:

• Handle all backend communication
• Provide type-safe data fetching
• Manage authentication state

Client-Side Requests

For client-side API requests:

• Recommended: Use react-query
• Maintain type safety with generated client
• Handle authentication through the API client