src/app/api/v1/API_STRUCTURE.md

API Structure Documentation

Structure

/src/app/api/v1/
├── definitions/
│   ├── route.ts                                  GET /api/v1/definitions
│   └── [definitionId]/
│       └── rounds/
│           └── route.ts                          GET /api/v1/definitions/{id}/rounds
├── rounds/
│   ├── route.ts                                  GET /api/v1/rounds
│   ├── metadata/
│   │   └── route.ts                              GET /api/v1/rounds/metadata
│   └── [roundId]/
│       ├── route.ts                              GET /api/v1/rounds/{id}
│       ├── leaderboard/
│       │   └── route.ts                          GET /api/v1/rounds/{id}/leaderboard
│       ├── models/
│       │   └── route.ts                          GET /api/v1/rounds/{id}/models
│       └── series/
│           ├── route.ts                          GET /api/v1/rounds/{id}/series
│           └── [seriesId]/
│               ├── data/
│               │   └── route.ts                  GET /api/v1/rounds/{id}/series/{id}/data
│               └── forecasts/
│                   └── route.ts                  GET /api/v1/rounds/{id}/series/{id}/forecasts
└── models/
    ├── rankings/
    │   └── route.ts                              GET /api/v1/models/rankings
    ├── ranking-filters/
    │   └── route.ts                              GET /api/v1/models/ranking-filters
    └── [modelId]/
        ├── route.ts                              GET /api/v1/models/{id}
        ├── rankings/
        │   └── route.ts                          GET /api/v1/models/{id}/rankings
        ├── series-by-definition/
        │   └── route.ts                          GET /api/v1/models/{id}/series-by-definition
        └── definitions/
            └── [definitionId]/
                └── series/
                    └── [seriesId]/
                        └── forecasts/
                            └── route.ts          GET /api/v1/models/{id}/definitions/{id}/series/{id}/forecasts

Service Layer

The service layer has been organized into three domain-specific files:

definitionService.ts

Handles challenge definition-related API calls:

• getDefinitionRounds() - Get rounds for a specific definition

roundService.ts

Handles round-related API calls:

• getChallenges() - List all rounds (previously called challenges)
• getRoundsMetadata() - Get filter metadata
• getChallengeSeries() - Get series for a round
• getSeriesData() - Get time series data
• getSeriesForecasts() - Get forecasts for a series
• getRoundModels() - Get models participating in a round

modelService.ts

Handles model-related API calls:

• getFilteredRankings() - Get model rankings with filters
• getRankingFilters() - Get available ranking filters
• getModelDetails() - Get model details
• getModelRankings() - Get model ranking history
• getModelSeriesByDefinition() - Get series grouped by definition
• getModelSeriesForecasts() - Get model forecasts across rounds

Authentication

All API routes forward the X-API-Key header to the backend API for authentication.