Verwandte Artikel:
https://bewotec-wiki.atlassian.net/wiki/spaces/MYJ/pages/221610003
https://bewotec-wiki.atlassian.net/wiki/spaces/MYJ/pages/221970481

Lunar ist eine Schnittstelle, mit der myJACK-Daten für Drittanwenungen bereit gestellt werden und es diesen Anwendungen ermöglicht wird, Daten in myJACK zu verändern.

API

Der Lunar-Service bietet eine GraphQL-API an.
GraphQL ist eine Query-Sprache für APIs, mit der der Nutzer auswählen kann, welche Informationen geliefert werden sollen.
Das ermöglicht eine effiziente Verarbeitung von großen Datenmodellen, besonders im Bezug auf Websites und mobile Geräte.
Eine ausführliche Dokumentation und Erklärung zur Sprache und Benutzung kann auf der GraphQL-Website gefunden werden und ist nicht Bestandteil dieser Dokumentation.

Authentifizierung und Autorisierung

Zur Authentifizierung und Autorisierung wird das OpenID-Connect -Protokoll verwendet.
Clients fordern dazu am Authentifizierungs-Server ein Token an, welches dann bei Requests an die Lunar-API als http-Header mitgesendet wird.
Unsere Kunden können die Passwörter für Ihre Zugänge selbst pflegen und aktualisieren.

Umgebungen

Wir bieten unseren Kunden für die Anbindung von myJACK mittels des Lunar-Service eine Umgebung für Tests und eine Umgebung für den produktiven Betrieb an.
In beiden Umgebungen sind vier Endpunkte von Bedeutung, die im weiteren erklärt werden.

Endpunkte

Account

Der Account-Endpunkt dient zur initialen Freischaltung Ihres Accounts. Sie erreichen so die Funktion "Passwort vergessen", um Ihr Passwort zu ändern.

OpenID-Connect

Über den OpenID-Connect Endpunkt kann ein Zugangstoken für die Lunar-API abgerufen werden.

GraphQL

An diesen Endpunkt werden die GraphQL-Anfragen gesendet.

GraphiQL

Unter dieser URL können Sie sich im Browser einen Editor für online GraphQL-Abfragen öffnen und so GraphQL-Abfragen direkt im Browser ausführen.

Open

Der GraphiQL-Editor dient zur Entwicklung von Queries. Dafür bietet der Editor auf der linken Seite einen Query-Editor mit Syntax-Highlightning und Auto-Vervollständigung.
Rechts daneben wird die Ausgabe der ausgeführten Query angezeigt. Die Query selbst kann entweder über den Play-Knopf oben links oder mithilfe von <STRG> + <ENTER>.
Über den Knopf oben rechts lässt sich ein Seitenmenü öffnen. Dort lässt sich das myJACKDatenmodell und seine Dokumentation (in GraphQL "Schema" genannt) ansehen.

Testumgebung

Ihr Account wird zunächst in der Test-Umgebung (UAT = User Acceptance Test) freigeschaltet,
gegen die Sie dann Ihre Abfragen implementieren.

Produktionsumgebung

Authentifizierung

Um den geschützten Endpoint abfragen zu können, braucht man zuerst einen Access-Token. Dieser wird über das OpenID-Connect Protokoll abgerufen.
Der Access-Token muss bei jeder Anfrage auf einen geschützten Endpoint als Bearer im Authorization Header mitgeliefert werden.
Hier ein Beispiel, wie ein Token mit http angefordert werden kann:

Token anfordern

grant_type: OpenID-Connect direct grant password flow
client_id: Client-ID ist 'lunar'
username: Username, wie er nach dem Login auf der Account-Seite angezeigt wird
password: Das von Ihnen gewählte Passwort

Und hier eine beispielhafte Antwort:
Response

access_token: Access-Token (JWT = Json-Web-Token)
espires_in: Gültigkeitsdauer des Token in Sekunden, hier also 300 Sekunden = 5 Minuten
refresh_token: Refresh-Token (JWT)
refresh_expires_in: Gültigkeitsdauer des Refresh-Token in Sekunden = 30 Minuten
token_type: Der Access-Token kann nur als Bearer verwendet werden

Aktivierung des Accounts im Test-System

Damit Sie das Testsystem nutzen können, müssen Ihre Zugangsdaten einmalig aktiviert werden.
Führen Sie dazu bitte die unten aufgeführten Schritte aus.

Schritt 1

Rufen Sie https://services.webtravel.de/myjack-stage/keycloak/auth/ mit Ihrem Browser auf und
klicken Sie dort auf <Passwort vergessen?>

Open

Schritt 2

In der nun folgenden Maske tragen Sie Ihre E-Mail-Adresse ein (Ihren Benutzernamen kennen Sie
jetzt noch nicht) und klicken auf <Absenden>.

Schritt 3

Sie erhalten nun innerhalb von 5 Minuten eine E-Mail, die einen Link zum Ändern Ihrers Passwortes enthält. Nach dem Klicken auf < Absenden > (im vorherigen Schritt) ist dieser Link dann für 5 Minuten gültig.
Sie können die Schritte 1 und 2 jederzeit wiederholen, um einen neuen Link zum Zurücksetzen des Passwortes generieren zu lassen.

Schritt 4

Bei der intialen Aktivierung Ihres Accounts erhalten Sie dann noch eine weitere E-Mail, in der Sie
aufgefordert werden, Ihre Mail-Adresse zu bestätigen.
Folgen Sie auch der Anleitung in dieser Mail.

Schritt 5

Nun können Sie sich unter https://services.webtravel.de/myjack-stage/keycloak/auth/ erneut mit Ihrer E-Mail-Adresse und Ihrem Passwort anmelden.
So gelangen Sie zur Seite <Benutzerkonto bearbeiten>. Dieser Seite können Sie Ihren Benutzernamen für die OpenID-Connect Anmeldung am Lunar-Service entnehmen: