# API Overview This document describes the HTTP API exposed by the application using Next.js **Route Handlers** in the App Router (`app/api/*/route.js`). All routes below are served under the `/api` prefix. --- ## 1. Configuration Dependencies The API expects a valid server configuration. Required environment variables: - `MONGODB_URI` — database connection string (used by `lib/db.js`). - `SESSION_SECRET` — JWT signing secret for session cookies. - `NAS_ROOT_PATH` — NAS mount root for storage operations. Optional environment variables: - `SESSION_COOKIE_SECURE` — override for the cookie `Secure` flag (`true`/`false`). The environment can be validated via: - `lib/config/validateEnv.js` - `scripts/validate-env.mjs` In Docker/production-like runs, execute `node scripts/validate-env.mjs` before starting the server to fail fast. --- ## 2. Authentication & Authorization ### 2.1 Sessions Authentication uses a signed JWT stored in an HTTP-only cookie (`auth_session`). To access protected endpoints: 1. `POST /api/auth/login` to obtain the cookie. 2. Send subsequent requests with that cookie. Notes: - In production-like setups, cookies should be `Secure` and the app should run behind HTTPS. - For local HTTP testing (`http://localhost:3000`), set `SESSION_COOKIE_SECURE=false` in your local docker env file. ### 2.2 RBAC (Branch-Level) RBAC is enforced on filesystem-related endpoints. - **401 Unauthorized**: no valid session - **403 Forbidden**: session exists but branch access is not allowed --- ## 3. General Conventions - All endpoints return JSON. - Error responses use: ```json { "error": "Human-readable error message" } ``` - Route handlers use Web `Request` / `Response` primitives. - For dynamic routes, Next.js 16 resolves parameters asynchronously via `ctx.params`. --- ## 4. Endpoints ### 4.1 `GET /api/health` **Purpose** Health check endpoint: - Verifies database connectivity (`db.command({ ping: 1 })`). - Verifies readability of `NAS_ROOT_PATH`. **Authentication**: not required. **Response 200 (example)** ```json { "db": "ok", "nas": { "path": "/mnt/niederlassungen", "entriesSample": ["@Recently-Snapshot", "NL01", "NL02"] } } ``` --- ### 4.2 `POST /api/auth/login` **Purpose** Authenticate a user and set the session cookie. **Authentication**: not required. **Request body (JSON)** ```json { "username": "example.user", "password": "plain-text-password" } ``` **Responses** - `200 { "ok": true }` - `400 { "error": "Invalid request body" }` - `400 { "error": "Missing username or password" }` - `401 { "error": "Invalid credentials" }` - `500 { "error": "Internal server error" }` --- ### 4.3 `GET /api/auth/logout` **Purpose** Destroy the current session by clearing the cookie. **Authentication**: recommended (but endpoint is idempotent). **Response** - `200 { "ok": true }` --- ### 4.4 `GET /api/branches` Returns the list of branches (e.g. `["NL01", "NL02"]`). **Authentication**: required. **RBAC behavior** - `branch` role → only own branch - `admin`/`dev` → all branches **Response 200** ```json { "branches": ["NL01", "NL02"] } ``` --- ### 4.5 `GET /api/branches/[branch]/years` Example: `/api/branches/NL01/years` **Authentication**: required. **Response 200** ```json { "branch": "NL01", "years": ["2023", "2024"] } ``` --- ### 4.6 `GET /api/branches/[branch]/[year]/months` Example: `/api/branches/NL01/2024/months` **Authentication**: required. **Response 200** ```json { "branch": "NL01", "year": "2024", "months": ["01", "02", "10"] } ``` --- ### 4.7 `GET /api/branches/[branch]/[year]/[month]/days` Example: `/api/branches/NL01/2024/10/days` **Authentication**: required. **Response 200** ```json { "branch": "NL01", "year": "2024", "month": "10", "days": ["01", "23"] } ``` --- ### 4.8 `GET /api/files?branch=&year=&month=&day=` Example: ```text /api/files?branch=NL01&year=2024&month=10&day=23 ``` **Authentication**: required. **Response 200** ```json { "branch": "NL01", "year": "2024", "month": "10", "day": "23", "files": [{ "name": "test.pdf", "relativePath": "NL01/2024/10/23/test.pdf" }] } ``` --- ## 5. Adding New Endpoints When adding new endpoints: 1. Define URL + method. 2. Implement a `route.js` under `app/api/...`. 3. Use `lib/storage` for filesystem access. 4. Enforce RBAC (`getSession()` + `canAccessBranch()` as needed). 5. Add route tests (Vitest). 6. Update this document.