# UNHCR Dashboard API Middleware

This is the API middleware for the UNHCR Dashboard. It provides cached access to UNHCR data with optimized performance and geographic data support.

## Available Endpoints

### Public API Endpoints

- **GET /api/datasets** - Get all available datasets
- **GET /api/:dataset/options** - Get filter options for a specific dataset
- **GET /api/data** - Get filtered dataset data
- **GET /api/summary** - Get summary statistics across datasets
- **GET /api/geo** - Get geographic data for mapping

## Quick Reference

| Endpoint | Description | Key Parameters |
|----------|-------------|----------------|
| `/api/datasets` | Returns all available datasets with their units | None |
| `/api/:dataset/options` | Returns available filter options for a dataset | `dataset` (path param) |
| `/api/data` | Returns filtered and aggregated dataset data | `dataset`, `yearsMode`, `selectedYears`, `level`, `category` |
| `/api/summary` | Returns summary statistics for key datasets | `selectedYears` |
| `/api/geo` | Returns geographic data for visualization | `geoLevelId`, `selectedYears`, `geoLevelValue` (optional) |

## Documentation

For comprehensive API documentation including:
- Detailed parameter descriptions
- Response formats and examples
- Error handling
- Environment configuration

Please refer to the [API Documentation](https://github.com/unhcr/dashboards/blob/main/api-middleware/API_DOCUMENTATION.md)

## Features

- **Two-tier caching** - Server-side (Cloudflare KV) and browser-side (HTTP) caching for optimal performance
- **CORS support** - Configurable cross-origin resource sharing
- **Parameter validation** - Automatic validation using Zod schemas
- **Geographic data** - Specialized endpoint for map visualizations
- **Error handling** - Detailed error responses for debugging

## Response Format

All endpoints return JSON responses with appropriate HTTP status codes:
- `200` - Success
- `400` - Validation error (with detailed error information)
- `500` - Server error

## Example Usage

### Get all datasets
```
GET /api/datasets
```

### Get options for a specific dataset
```
GET /api/budget/options
```

### Get filtered data
```
GET /api/data?dataset=budget&yearsMode=multiple&selectedYears[]=2024&level=country&category=all
```

### Get summary for specific years
```
GET /api/summary?selectedYears[]=2023&selectedYears[]=2024
```

### Get geographic data
```
GET /api/geo?geoLevelId=CTY&selectedYears[]=2024
```

---

*For detailed documentation, see API_DOCUMENTATION.md*