jagd-apps/nachsuche/docs/API.md

# API-Dokumentation

## Basis-URL
```
http://localhost:5000/api
```

## Authentifizierung

Die meisten Endpunkte erfordern eine Authentifizierung über JWT-Token. Das Token muss im Authorization-Header mitgeführt werden:

```
Authorization: Bearer <token>
```

## Öffentliche Endpunkte

### GET /api/public/users
Ruft alle verfügbaren Nachsuchenführer ab.

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "_id": "...",
      "name": "Frank Dahlem",
      "address": "Neues Land 17, 29649 Wietzendorf",
      "phone": "05196-3849802",
      "type": "HS",
      "available": true,
      "gps": {
        "lat": 52.5,
        "lng": 9.5
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

## Authentifizierung

### POST /api/auth/login
Admin-Login.

**Request Body:**
```json
{
  "username": "admin",
  "password": "password"
}
```

**Response:**
```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "...",
    "username": "admin"
  }
}
```

## Geschützte Endpunkte (Admin)

### GET /api/users
Ruft alle Nachsuchenführer ab (auch nicht verfügbare).

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "success": true,
  "data": [...]
}
```

### GET /api/users/:id
Ruft einen einzelnen Nachsuchenführer ab.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "success": true,
  "data": {...}
}
```

### POST /api/users
Erstellt einen neuen Nachsuchenführer.

**Headers:**
- `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "name": "Max Mustermann",
  "address": "Musterstraße 1, 12345 Musterstadt",
  "phone": "01234-567890",
  "type": "HS",
  "available": true,
  "gps": {
    "lat": 52.5,
    "lng": 9.5
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {...}
}
```

### PUT /api/users/:id
Aktualisiert einen Nachsuchenführer.

**Headers:**
- `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "name": "Max Mustermann",
  "address": "Neue Adresse",
  ...
}
```

**Response:**
```json
{
  "success": true,
  "data": {...}
}
```

### DELETE /api/users/:id
Löscht einen Nachsuchenführer.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "success": true,
  "message": "Benutzer erfolgreich gelöscht"
}
```

### PUT /api/users/:id/availability
Aktualisiert die Verfügbarkeit eines Nachsuchenführers.

**Headers:**
- `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "available": true
}
```

**Response:**
```json
{
  "success": true,
  "data": {...}
}
```

### PUT /api/users/:id/gps
Aktualisiert die GPS-Koordinaten eines Nachsuchenführers.

**Headers:**
- `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "lat": 52.5,
  "lng": 9.5
}
```

**Response:**
```json
{
  "success": true,
  "data": {...}
}
```

### GET /api/users/export
Exportiert alle Nachsuchenführer.

**Headers:**
- `Authorization: Bearer <token>`

**Query Parameters:**
- `format`: `csv` oder `json` (Standard: `json`)

**Response:**
- CSV: Datei-Download
- JSON: JSON-Objekt mit allen Benutzern

## Fehlerbehandlung

Alle Fehler folgen diesem Format:

```json
{
  "success": false,
  "message": "Fehlermeldung"
}
```

**HTTP-Status-Codes:**
- `200`: Erfolg
- `201`: Erstellt
- `400`: Ungültige Anfrage
- `401`: Nicht authentifiziert
- `403`: Nicht autorisiert
- `404`: Nicht gefunden
- `500`: Serverfehler