1. Einleitung

Lange Zeit wurden Web-Applikationen als Konglomerat von vielen statischen Webseiten realisiert. Mittlerweile haben sich dynamische Web-Applikationen als Standard etabliert. Eine typische Herausforderung, die bei der Entwicklung so einer Applikation immer wieder erneut gemeistert werden muss, ist die Bereitstellung einer Navigation. Dabei ist es notwendig, einen strukturierten Zusammenhang zwischen durch Menschen lesbaren URL-Pfaden und den tatsächlichen Inhalten, die von anderen Quellen dynamisch geladen werden müssen, herzustellen. Die Applikation muss wissen, was abhängig von der URL angezeigt werden soll.

Bisher war dies eine Aufgabe, die für jede Web-Applikation stets erneut individuell gelöst werden musste. Nun bietet der Navigation Service ein standartisiertes Format, sodass Lösungen in Zukunft wiederverwendet werden können. Die Verantwortlichen können sich weniger auf technische Details und besser auf den Mehrwert ihrer Applikation konzentrieren.

Der Navigation Service ist ein Produkt der Crownpeak Technology GmbH, welches ausschließlich als Software-as-a-Service-Dienst in der Cloud angeboten wird. Selbst gehostete Instanzen werden nicht unterstützt.

2. Technischer Überblick

Der Navigation Service ist ein Dienst, der die Bereitstellung von Navigationen in dynamischen (Web-)Applikationen erleichtert. Hierzu bietet er eine REST-API, über die Navigationen in einem geeigneten Format im Navigation Service gespeichert und später wieder ausgelesen werden können. Hierbei können sie sowohl vollständig abgerufen als auch auf geeignete Weisen gefiltert werden. Das Kapitel Features erläutert die einzelnen Funktionen des Navigation Services im Detail.

2.1. Typische Anwendungsfälle

Der Navigation Service ist als Teil der Auslieferungsschicht anzusehen. Im klassischen Anwendungsfall wird als erstes eine Navigation im Navigation Service persistiert. Die URL, unter der diese Navigation nun erreichbar ist, wird in einer dynamischen (Web-)Applikation hinterlegt. Bei jedem Aufruf der Applikation holt sie sich die Navigation vom Navigation Service und ist nun in der Lage dem Nutzer den korrekten Inhalt anzuzeigen.

Im FirstSpirit-Universum übernimmt die Persistierung und Aktualisierung der Navigationen im Navigation Service das Navigation FirstSpirit-Modul. Dies ermöglicht es Redakteuren Inhalte in FirstSpirit zu editieren, wonach die Änderungen automatisch in der Navigation widergespiegelt werden. Auf diese Weise können neue Inhalte in Applikationen angezeigt werden, ohne dass die Applikationen selbst verändert werden müssen.

2.2. OpenAPI-Spezifikation

Die OpenAPI-Spezifikation ist ein Standard zur Beschreibung von REST-konformen Programmierschnittstellen. Der Navigation Service bietet eine OpenAPI-Spezifikation inklusive folgender Ressourcen:

2.3. Format einer Navigation

Sämtliche Kommunikation mit dem Navigation Service findet in JSON statt. Primär werden dabei Navigationen entweder abgefragt oder persistiert. Dabei werden Navigationen als Baum abgebildet, wobei jedes Element des Baums ein Navigationselement darstellt.

Beispiel: Navigation in JSON 
{
    "id": "815c307c-2ca6-4f02-9653-fa3454988fc2",
    "label": "Produkte",
    "seoRoute": "/Produkte",
    "seoRouteRegex": null,
    "contentReference": "/Produkte/Verkauf/index.html",
    "visible": true,
    "permissions": null,
    "customData": {
        "pageDescription": "Unser Produktangebot"
    },
    "children": [
        {
            "id": "4424cbd7-c6df-4d7b-b916-cfe641754fd5",
            "label": "Koffer",
            "seoRoute": "/Produkte/:item",
            "seoRouteRegex": "^[\\/]Produkte\\/[^\\s\\/]+$",
            "contentReference": "/Produkte/Verkauf/koffer.html",
            "visible": true,
            "permissions": {
                "allowed": ["customer", "admin"],
                "forbidden": ["anonym"]
            },
            "customData": {
                "available": false
            },
            "children": null
        }
    ]
}

In der nachfolgenden Tabelle wird die fachliche Bedeutung der einzelnen Attribute erläutert:

Name Beschreibung

id

Die eindeutige Id des Navigationselements.

label

Der Name des Navigationselements zur Darstellung auf der Webseite.

seoRoute

Die URL, zu der dieses Navigationselement führt. Typischerweise die URL, die später im Browser in der URL-Zeile angezeigt wird.

seoRouteRegex

Es kann sein, dass die seoRoute Variablen enthält. Um in diesem Fall die konkreten Ausprägungen dem Navigationselement dennoch zuordnen zu können kann eine entsprechende Regex hinterlegt werden.

contentReference

Die URL zum Inhalt, welchen die Applikation abfragen und dem Nutzer aufbereitet darstellen muss. In einem Headless-FirstSpirit-Projekt könnte dies beispielsweise eine CaaS-URL sein, unter der die Seiteninformationen bereitgestellt werden.

visible

Spezifiziert, ob das Navigationselement im Frontend in der Navigation angezeigt werden soll.

permissions

Enthält Informationen über Rollen, die dieses Navigationselement sehen dürfen.

customData

Beliebige Key/Value-Paare, die es ermöglichen individuelle Anforderungen der Applikation abzubilden. Die Anzahl der Werte ist auf maximal fünf begrenzt. Die Werte müssen vom Typ Number, Boolean oder String sein, Objekte und Arrays sind hier nicht zugelassen.

children

Eine Liste von Navigationselementen, die dieselben Attribute (id, label, etc.) besitzen. Hierdurch wird eine Baumstruktur realisiert.

Eine detaillierte technische Dokumentation der einzelnen Endpunkte entnehmen Sie bitte der OpenAPI-Spezifikation.

3. Features

Die nachfolgenden Unterkapitel beschreiben die Features des Navigation Services aus einer fachlichen Perspektive. Sie verlinken dabei zusätzlich auf den entsprechenden Endpunkt in der Swagger UI. Alternative Darstellungen finden Sie im Abschnitt OpenAPI-Spezifikation.

3.1. Sprachen-Fallbacks

Navigationen lassen sich im Navigation Service über ihre Id und Sprache eindeutig identifizieren. Sprachen werden hierbei stets als ISO 639 Code spezifiziert (z.B. de). Länder werden als ISO 3166-1 Code spezifiziert (z.B. AT).

Es werden lediglich Sprach- und Ländercodes mit 2 Buchstaben unterstützt. Weitere Darstellungen der Codes durch 3 Buchstaben (ISO 639-2/3 und ISO 3166-1 alpha-3) oder numerische Codes (UN M49 Ziffern) werden nicht unterstützt.

Existiert eine angefragte Navigation zwar in einer allgemeinen Sprache, jedoch nicht in der angefragten Variante, so erfolgt ihre Auslieferung in der allgemeinen Sprache.

Beispiel:

  1. Vorhanden: (de)

  2. Angefragt: (de_AT)

  3. Ausgeliefert: (de)

Es ist zu beachten, dass das Fallback-Verhalten nur in eine Richtung funktioniert. Der Navigation Service kann nur auf allgemeinere Navigationen ausweichen, nicht jedoch auf spezifischere.

Beispiel:

  1. Vorhanden: (de_AT)

  2. Angefragt: (de)

  3. Ausgeliefert: N/A

3.2. API Endpunkte

Die nachfolgenden Endpunkte realisieren die Funktionen des Navigation Services.

Auflistung

Es ist möglich sich alle verfügbaren Navigationen auflisten zu lassen. Die Navigationen werden paginiert als Liste bereitgestellt.
Die OpenAPI-Spezifikation zur Auflistung enthält weiterführende Informationen.

Vollständige Navigationen bearbeiten

Der Navigation Service ermöglicht die Persistierung, Abfrage, Aktualisierung und Löschung von Navigationen.
Die OpenAPI-Spezifikation zu CRUD Operationen enthält weiterführende Informationen.

Teilbäume bearbeiten

Anstelle von vollständigen Navigation lassen sich auch mögliche Teilbäume abfragen. Die Identifikation des Navigationselements erfolgt anhand seiner Id. Anschließend wird es mit allen Kind-Elementen ausgeliefert. Enthält die Navigation mehrere Elemente mit der gleichen ID, wird das erste gefundene zurückgegeben. Außerdem ist es möglich Teilbäume einer Navigation zu aktualisieren.
Die OpenAPI-Spezifikation zu Teilbäumen enthält weiterführende Informationen.

Breadcrumbs

Ein typisches Feature einer Web-Applikation ist eine Breadcrumbs-Ansicht, die den Pfad zum aktuell dargestellten Element der Applikation abbildet. Um dieses Szenario zu realisieren, bietet der Navigation Service die Möglichkeit, ausschließlich die Navigationselemente zwischen der Wurzel und dem konkreten Navigationselement als Liste abzufragen.
Die OpenAPI-Spezifikation zu Breadcrumbs enthält weiterführende Informationen.

Teilbäume anhand SEO-Routen identifizieren

Ein klassisches Szenario ist, dass ein Nutzer eine Unterseite der Web-Applikation direkt über ihre URL aufruft. Dabei kann es sein, dass nur die Navigation für den entsprechenden Unterbaum für die Anzeige benötigt wird. Hierfür bietet der Navigation Service die Möglichkeit Unterbäume nicht nur anhand der Id, sondern auch anhand des seoRoute-Attributs abzufragen. Falls eine seoRoute Variablen enthält, wird die Navigation anhand des seoRouteRegex identifiziert.
Die OpenAPI-Spezifikation zu SEO-Routen enthält weiterführende Informationen.

4. Authentifizierung/Autorisierung

Im Folgenden wird das Authentifizierungs-/Autorisierungskonzept des Navigation Services vorgestellt.

4.1. POST, PUT, DELETE

Da die Endpunkte des Navigation Services frei aus dem Internet erreichbar sind, müssen alle Schreiboperationen explizit gesichert werden. Dies stellt sicher, dass die Änderung oder Löschung von im Navigation Service persistierter Navigationen ausschließlich mit einer entsprechenden Berechtigung erfolgen kann. Hierfür wird ein von Crownpeak Technology GmbH gehostetes internes Identitäts- und Zugriffsmanagementsystem verwendet, bei welchem OAuth-konform ein gültiger Access Token abgefragt und an den Navigation Service bei jedem PUT, POST und DELETE übermittelt werden muss.

Die Authentifizierung/Autorisierung wird automatisch vom Navigation FirstSpirit-Modul übernommen.

4.2. GET

In der Standardeinstellung sind lesende Anfragen nicht geschützt, entsprechend sind alle dem Navigation Service bekannten Informationen im Internet frei verfügbar. Sensitive Informationen dürfen daher nicht Teil der Navigation einer Webseite sein.

4.3. Konfiguration

Es ist möglich, das oben beschriebene Standardverhalten sowohl für Lese- als auch für Schreiboperationen zu konfigurieren. Sie können z.B. die Authentifizierung für Schreibvorgänge komplett deaktivieren oder sicherstellen, dass einige Navigationen auch für Leseanfragen eine Authentifizierung erfordern. Siehe OpenAPI Spezifikation für weitere Details.

5. Navigation FirstSpirit-Modul

Seitens FirstSpirit gibt es eine Integration mit dem Navigation Service durch das Navigation FirstSpirit-Modul. Sofern es auf dem Server installiert und im Projekt aktiviert ist, werden in FirstSpirit gepflegte Navigationen automatisch im Navigation Service bereitgestellt.

6. Rechtliche Hinweise

Der Navigation Service ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.

Für die Verwendung des Produkts gilt gegenüber dem Anwender nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

7. Hilfe

Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.