mein-sterntours/dev/frontend-navigation/navigation-api.md

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

"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:

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

Country:

"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:

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

HTTP Status Codes:

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

---

Verwendungsbeispiele

JavaScript/Fetch

// 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

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

# 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.