# Navigation API Dokumentation

Die Navigation-API stellt Endpunkte bereit, um die Frontend-Navigationsstruktur im Backend abzurufen.

## Basis-URL

Alle Endpunkte sind unter `/api/navigation/` verfügbar.

## Endpunkte

### 1. Kompletter Navigationsbaum

**GET** `/api/navigation/tree`

Gibt den kompletten hierarchischen Navigationsbaum mit allen Seiten zurück.

**Response:**

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Startseite",
      "title_short": null,
      "before_title": null,
      "slug": "startseite",
      "real_url_path": "/",
      "url": "/",
      "status": 1,
      "show_in_navi": 1,
      "order": 1,
      "template": "home",
      "lvl": 0,
      "parent_id": null,
      "pagetitle": "Willkommen",
      "description": "Startseite",
      "keywords": "start, home",
      "canonical_url": null,
      "lft": 1,
      "rgt": 10,
      "tree_root": 1,
      "box_body": null,
      "box_image_url": null,
      "box_star": null,
      "box_discount": null,
      "is_travel_program": false,
      "is_fewo_lodging": false,
      "is_country_page": false,
      "cms_settings": null,
      "children": [
        {
          "id": 2,
          "title": "Über uns",
          "slug": "ueber-uns",
          "url": "/ueber-uns",
          "children": [],
          "has_children": false
        }
      ],
      "has_children": true
    }
  ],
  "meta": {
    "total_nodes": 42,
    "generated_at": "2024-01-15T10:30:00+00:00"
  }
}
```

---

### 2. Nur aktive Navigationspunkte

**GET** `/api/navigation/tree/active`

Gibt nur aktive Seiten zurück (`status = 1` und `show_in_navi = 1`).

**Response:** Gleiche Struktur wie oben, aber gefiltert.

---

### 3. Teilbaum ab einem bestimmten Knoten

**GET** `/api/navigation/tree/{rootId}`

Gibt einen Teilbaum zurück, beginnend mit der angegebenen Page-ID.

**Parameter:**

- `rootId` (integer): Die ID der Seite, ab der der Baum aufgebaut werden soll

**Beispiel:** `/api/navigation/tree/5`

**Response:**

```json
{
  "success": true,
  "data": {
    "id": 5,
    "title": "Reisen",
    "slug": "reisen",
    "url": "/reisen",
    "children": [
      {
        "id": 6,
        "title": "Türkei",
        "slug": "tuerkei",
        "url": "/reisen/tuerkei",
        "children": [],
        "has_children": false
      }
    ],
    "has_children": true
  },
  "meta": {
    "total_nodes": 15,
    "generated_at": "2024-01-15T10:30:00+00:00"
  }
}
```

---

### 4. Flache Liste (ohne Hierarchie)

**GET** `/api/navigation/flat`

Gibt alle Navigationspunkte als flache Liste zurück (ohne parent-child Beziehung).

**Response:**

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Startseite",
      "slug": "startseite",
      "url": "/",
      "status": 1,
      "show_in_navi": 1,
      "order": 1,
      "template": "home",
      "lvl": 0,
      "parent_id": null,
      "is_travel_program": false,
      "is_fewo_lodging": false,
      "is_country_page": false
    },
    {
      "id": 2,
      "title": "Über uns",
      "slug": "ueber-uns",
      "url": "/ueber-uns",
      "status": 1,
      "show_in_navi": 1,
      "order": 2,
      "template": "default",
      "lvl": 0,
      "parent_id": null,
      "is_travel_program": false,
      "is_fewo_lodging": false,
      "is_country_page": false
    }
  ],
  "meta": {
    "total_nodes": 42,
    "generated_at": "2024-01-15T10:30:00+00:00"
  }
}
```

---

### 5. Breadcrumb-Pfad

**GET** `/api/navigation/breadcrumb/{pageId}`

Gibt den Breadcrumb-Pfad für eine bestimmte Seite zurück (von der Wurzel bis zur Zielseite).

**Parameter:**

- `pageId` (integer): Die ID der Seite, für die der Breadcrumb erstellt werden soll

**Beispiel:** `/api/navigation/breadcrumb/15`

**Response:**

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Startseite",
      "title_short": null,
      "url": "/",
      "slug": "startseite"
    },
    {
      "id": 5,
      "title": "Reisen",
      "title_short": null,
      "url": "/reisen",
      "slug": "reisen"
    },
    {
      "id": 10,
      "title": "Türkei",
      "title_short": null,
      "url": "/reisen/tuerkei",
      "slug": "tuerkei"
    },
    {
      "id": 15,
      "title": "Istanbul",
      "title_short": null,
      "url": "/reisen/tuerkei/istanbul",
      "slug": "istanbul"
    }
  ],
  "meta": {
    "depth": 4,
    "generated_at": "2024-01-15T10:30:00+00:00"
  }
}
```

---

## Felder-Beschreibung

Jeder Navigationspunkt enthält folgende Informationen:

### Basis-Informationen

- `id`: Eindeutige ID der Seite
- `title`: Vollständiger Titel
- `title_short`: Kurzer Titel (optional)
- `before_title`: Text vor dem Titel (optional)
- `slug`: URL-freundlicher Name
- `real_url_path`: Der definierte URL-Pfad aus der Datenbank
- `url`: Der vollständige URL-Pfad (entweder `real_url_path` oder automatisch generiert)

### Navigationsinformationen

- `status`: Status der Seite (0 = inaktiv, 1 = aktiv)
- `show_in_navi`: Soll in Navigation angezeigt werden (0 = nein, 1 = ja)
- `order`: Sortierreihenfolge
- `lvl`: Hierarchie-Ebene (0 = Root)
- `parent_id`: ID der Eltern-Seite (null = Root)

### SEO-Informationen

- `pagetitle`: SEO-Titel
- `description`: Meta-Beschreibung
- `keywords`: Meta-Keywords
- `canonical_url`: Kanonische URL

### Template & Layout

- `template`: Template-Name (z.B. "home", "overview", "default")
- `box_body`: Inhalt für Box-Darstellung
- `box_image_url`: Bild-URL für Box
- `box_star`: Sternebewertung
- `box_discount`: Rabatt-Information

### Tree-Struktur

- `lft`, `rgt`: Nested Set Tree Werte
- `tree_root`: ID der Baumwurzel

### Content-Type Flags

- `is_travel_program`: Ist ein Reiseprogramm
- `is_fewo_lodging`: Ist eine Ferienwohnung
- `is_country_page`: Ist eine Länderseite

### Beziehungen (wenn vorhanden)

**Travel Program:**

```json
"travel_program": {
  "id": 123,
  "title": "7 Tage Istanbul",
  "subtitle": "Die schönsten Orte",
  "status": 1,
  "position": 1,
  "duration": 7,
  "price_from": 899.00
}
```

**Fewo Lodging:**

```json
"fewo_lodging": {
  "id": 45,
  "name": "Villa am Meer",
  "status": 1
}
```

**Country:**

```json
"country": {
  "id": 10,
  "name": "Türkei",
  "title": "Türkei Reisen",
  "slug": "tuerkei"
}
```

### Hierarchie-Informationen

- `children`: Array von Child-Knoten (gleiche Struktur)
- `has_children`: Boolean, ob Kinder vorhanden sind

---

## Fehlerbehandlung

Bei Fehlern wird ein JSON-Response mit folgendem Format zurückgegeben:

```json
{
  "success": false,
  "error": "Fehlerbeschreibung"
}
```

**HTTP Status Codes:**

- `200`: Erfolgreiche Anfrage
- `404`: Seite/Ressource nicht gefunden
- `500`: Serverfehler

---

## Verwendungsbeispiele

### JavaScript/Fetch

```javascript
// Kompletten Navigationsbaum abrufen
fetch("/api/navigation/tree")
  .then((response) => response.json())
  .then((data) => {
    console.log("Navigation Tree:", data.data);
    console.log("Total Nodes:", data.meta.total_nodes);
  });

// Breadcrumb für eine Seite abrufen
fetch("/api/navigation/breadcrumb/15")
  .then((response) => response.json())
  .then((data) => {
    console.log("Breadcrumb:", data.data);
  });
```

### PHP/Laravel

```php
use Illuminate\Support\Facades\Http;

// Kompletten Navigationsbaum abrufen
$response = Http::get('http://yourdomain.com/api/navigation/tree');
$navigationTree = $response->json()['data'];

// Teilbaum abrufen
$response = Http::get('http://yourdomain.com/api/navigation/tree/5');
$subTree = $response->json()['data'];
```

### cURL

```bash
# Kompletten Baum
curl -X GET http://yourdomain.com/api/navigation/tree

# Nur aktive Navigationspunkte
curl -X GET http://yourdomain.com/api/navigation/tree/active

# Breadcrumb
curl -X GET http://yourdomain.com/api/navigation/breadcrumb/15
```

---

## Performance-Hinweise

- Der komplette Navigationsbaum kann bei großen Websites viele Knoten enthalten
- Verwenden Sie `/api/navigation/tree/active` für Frontend-Navigationen
- Verwenden Sie `/api/navigation/tree/{rootId}` um nur relevante Teilbäume zu laden
- Erwägen Sie Caching für häufig abgerufene Navigationsstrukturen

---

## Implementierung

Die Navigation-API basiert auf folgenden Komponenten:

1. **Controller:** `App\Http\Controllers\API\NavigationController`
2. **Service:** `App\Services\NavigationTreeService`
3. **Model:** `App\Models\Page`
4. **Routen:** Definiert in `routes/api.php`

Der Service verwendet rekursive Methoden, um den hierarchischen Baum aufzubauen und kann einfach erweitert werden.