JSON API für mobile und externe Anwendungen

Eine Integration darf nicht von der Auszeichnung einer Webseite abhängen

Eine Unternehmensplattform ist keine isolierte Website mehr, wenn eine mobile Anwendung, ein Fahrerarbeitsplatz, ein internes Portal, ein Terminal oder ein Partnerdienst angebunden wird. Der Versuch, dafür HTML-Seiten zu verwenden, erzeugt schnell eine fragile Abhängigkeit vom Design. Ein direkter Datenbankzugang ist noch gefährlicher: Der externe Client beginnt, Geschäftsregeln zu wiederholen, Rechte zu ignorieren und von der internen Speicherstruktur abzuhängen.

Sapphire I.C.D.S. stellt für diese Aufgaben einen getrennten Integrationsbereich bereit: eine HTTPS JSON API. Sie nimmt strukturierte Anfragen an und liefert maschinenlesbare Antworten, rendert keine Benutzerseiten und verlangt vom Client keine Kenntnis der Serverdatenbank. Die öffentliche Roadmap dokumentiert diesen Bereich als veröffentlichte Grundlage für native Clients und Geschäftsintegrationen.

JSON ist das Austauschformat und nicht die gesamte Architektur

JSON allein macht eine Integration nicht zuverlässig. Entscheidend ist, wer den verfügbaren Befehl festlegt, wie Benutzer bestätigt werden und wo die Geschäftsvalidierung stattfindet. In Sapphire I.C.D.S. ist die System-API für die Authentifizierung zuständig, während Fachbefehle von Modulen über einen getrennten Vertrag veröffentlicht werden. Der Client sendet Aktion und Daten, der Server wählt jedoch das verantwortliche Modul, prüft die Anfrage und erzeugt das Ergebnis.

Dadurch können Weboberfläche, mobile Anwendung und externes System dieselbe Fachlogik verwenden. Eine Operation zum Speichern eines Lieferergebnisses muss beispielsweise Route, Geschäft, Produkt und Rechte des Ausführenden unabhängig davon gleich prüfen, welcher Bildschirm die Anfrage gesendet hat. Der Client verantwortet eine geeignete Oberfläche, das Modul die Korrektheit des Prozesses.

Sitzung und Identität werden serverseitig geprüft

Die API unterstützt den grundlegenden Lebenszyklus einer Clientsitzung: Anmeldung, Abfrage des aktuell bestätigten Benutzers, Erneuerung des Zugangs und Abmeldung. Nach erfolgreicher Anmeldung erhält der Client ein kurzlebiges Zugangstoken und ein getrenntes Aktualisierungstoken. Eine Aktualisierung ersetzt das Paar. Die Anwendung muss die neuen Werte deshalb atomar speichern und darf eine bereits erfolgreiche Operation nicht mit dem alten Wert wiederholen.

Der entscheidende Grundsatz lautet, dass Benutzer-, Gruppen- oder Objektfelder im JSON keine Berechtigung belegen. Der Server leitet die Identität aus der bestätigten Sitzung ab und bestimmt erst danach den verfügbaren Datenbereich. Ein Logistikmodul darf zum Beispiel keine andere Route anzeigen, weil der Client eine fremde Fahrerkennung eingesetzt hat. Die Verbindung zur Geschäftsrolle wird serverseitig aufgelöst.

Module veröffentlichen nur ausdrückliche Aktionen

Die dedizierte API öffnet nicht automatisch alle Funktionen von Sapphire I.C.D.S. Ein Modul muss einen API-Anbieter umsetzen und seine unterstützten Befehle aufzählen. Dadurch können Integrationen stufenweise veröffentlicht werden: zuerst sichere Leseoperationen, danach eng begrenzte Änderungen und nach der Prüfung komplexere Arbeitsabläufe. Ein Modul ohne externen Vertrag wird nicht allein durch seine Installation verfügbar.

Zustandsändernde Befehle müssen für Änderungen vorgesehene Anfragen verwenden, während das Lesen eine getrennte Operation bleiben kann. Der Server liefert verständliche Ergebniscodes für eine ungültige Anfrage, abgelaufene Sitzung, verweigerten Zugang, falsche Methode oder vorübergehend nicht verfügbare Abhängigkeit. Die Clientanwendung erhält einen definierten Behandlungspfad statt einer HTML-Fehlerseite.

• Der mobile Client sendet nur erforderliche Daten und speichert Tokens im geschützten Gerätespeicher.
• Der API-Bereich prüft Sitzung, Anfragemethode und zulässige Eingabegröße.
• Das Modul prüft Fachregeln, Benutzerbereich und erlaubte Zustandsübergänge.
• Die Datenbank bleibt hinter der Serverschicht und wird dem Client nicht direkt veröffentlicht.

Geeignete Geschäftsszenarien

Eine JSON API ist besonders nützlich, wenn Beschäftigte außerhalb des zentralen Backoffice arbeiten. In der Logistik kann dies die Liste zugewiesener Routen, Daten einer Verkaufsstelle oder die Erfassung gelieferter Mengen, Rückgaben und Dokumentzustände umfassen. Im Rechnungswesen kann es der Abruf eines Verzeichnisses und die Übermittlung einer bestätigten Operation sein. Eine externe Anwendung kann einen erlaubten Zustand lesen und einen bestimmten Befehl starten, ohne Browseraktionen zu simulieren.

Die öffentliche Roadmap nennt Logistik, Rechnungswesen und Außendienstprozesse als natürliche Entwicklungsrichtungen. Das bedeutet nicht, dass für jedes Szenario bereits ein universeller Endpunkt vorhanden ist. Die Reife wird durch den API-Befehlssatz des installierten Moduls bestimmt. Vor einem Integrationsprojekt ist eine Matrix aus Operationen, Daten, Rollen und Versionen zu erstellen.

Die JSON API ist kein externes MCP

Beide Bereiche verwenden strukturierte Daten, bedienen aber unterschiedliche Clientklassen. Die JSON API ist für mobile und Unternehmensanwendungen mit einem vorab entworfenen Benutzerprozess vorgesehen. Externes MCP dient kompatiblen AI-Clients, die Werkzeuge finden und in einer Agentensitzung aufrufen. Ihre Rechte und Veröffentlichungsrichtlinien dürfen nicht als austauschbar behandelt werden.

Die API ist auch keine entfernte SQL-Konsole, kein Generator beliebiger Berichte und kein Versprechen des Zugangs zu allen Tabellen. Sie stellt Geschäftsbefehle bereit, für die ein Modul verantwortlich ist. Diese Abstraktion ist widerstandsfähiger gegen Änderungen des Speicherschemas und sicherer für langfristige Pflege.

Aufgaben der Clientanwendung

Ein nativer Client muss Ablauf des Zugangstokens, Ersatz des Aktualisierungstokens, Abmeldung, Netzverlust und wiederholte Übermittlung korrekt behandeln. Bei zustandsändernden Operationen ist die Unterscheidung zwischen bestätigter Ablehnung und unklarem Transportergebnis besonders wichtig. Ohne vereinbarte Idempotenz darf eine möglicherweise serverseitig ausgeführte Aktion nicht automatisch wiederholt werden. Ein lokaler Cache ist keine Quelle aktueller Rechte.

Das technische Team legt außerdem Vertragsversionierung, Protokollierung, Anfragegrenzen und Strategie der Rückwärtskompatibilität fest. Die Plattform liefert den gemeinsamen modularen Bereich. Die Qualität eines konkreten mobilen Produkts hängt jedoch von der Disziplin des Clients und der Vollständigkeit des veröffentlichten Geschäftsvertrags ab.

Der Weg zur Einführung

Die Arbeit sollte mit einer Bestandsaufnahme der Benutzerszenarien und nicht mit einer Tabellenliste beginnen. Für jeden Schritt werden Eingabefelder, Antwort, Rolle, Datenbereich, zulässige Übergänge und Verhalten bei Wiederholung festgelegt. Danach veröffentlicht das Modul den minimalen Befehlssatz, das mobile Team baut die Oberfläche, und gemeinsame Tests prüfen erfolgreiche sowie verbotene Szenarien.

Für den Eigentümer entsteht die Möglichkeit, eigene Anwendungen ohne Duplizierung der Serverlogik zu entwickeln. Die technische Leitung erhält eine gesteuerte Integrationsgrenze mit gemeinsamer Authentifizierung und modularen Befehlen. Die JSON API erweitert Sapphire I.C.D.S. über die Weboberfläche hinaus, hält Daten, Rechte und Prozessregeln aber im maßgeblichen Serverbereich.