> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/igorek05m/daily-geogame/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Internal API architecture for Daily GeoGame

Daily GeoGame uses Next.js 15 App Router API routes to provide the backend functionality for the geography guessing game. All API routes are internal and used exclusively by the frontend application.

## Base URL

All API routes are relative to the application root:

```http theme={null}
/api/*
```

## Architecture

The API follows a serverless architecture using Next.js App Router conventions:

* Located in `app/api/` directory
* Each endpoint is a `route.ts` file exporting HTTP method handlers
* Built on Next.js `NextRequest` and `NextResponse` types
* Connected to MongoDB for data persistence
* Session-based user tracking via HTTP-only cookies

## Authentication

The API uses session-based authentication through HTTP-only cookies:

* **Session cookie**: `geo_session`
* Automatically created on first progress save
* UUID v4 format
* 10-year expiration
* Secure in production, HttpOnly, SameSite strict

No explicit authentication endpoints exist - sessions are created automatically when saving progress.

## Response format

All endpoints return JSON responses:

**Success response:**

```json theme={null}
{
  // Endpoint-specific data
}
```

**Error response:**

```json theme={null}
{
  "error": "Error message description"
}
```

## Error handling

Standard HTTP status codes are used:

| Status | Description                                              |
| ------ | -------------------------------------------------------- |
| 200    | Success                                                  |
| 400    | Bad Request - Invalid parameters or payload              |
| 500    | Internal Server Error - Database or external API failure |

<Note>
  The API gracefully handles database connection failures by falling back to in-memory data generation where possible.
</Note>

## Rate limiting

No explicit rate limiting is currently implemented. The API relies on Next.js serverless function limitations and caching strategies.

## Endpoints

<CardGroup cols={2}>
  <Card title="Daily game" icon="calendar" href="/api/daily">
    Get the daily geography challenge with hints
  </Card>

  <Card title="Country details" icon="flag" href="/api/country">
    Fetch country information from cache
  </Card>

  <Card title="User progress" icon="chart-line" href="/api/progress">
    Save and retrieve user game progress
  </Card>

  <Card title="Global statistics" icon="chart-bar" href="/api/stats">
    View global player statistics for a date
  </Card>
</CardGroup>

## External dependencies

The API integrates with external services:

* **RestCountries API**: Country details (name, flag, coordinates, borders)
* **CIA World Factbook**: Detailed country information for hints
* **MongoDB**: User progress and daily game persistence

<Warning>
  If external APIs fail, the system falls back to cached data or generates minimal game configurations.
</Warning>