Zum Inhalt

REST-Schnittstelle (OpenAPI)

Die XJustiz-Werkzeuge stellen ihre Funktionen über eine REST-Schnittstelle bereit. Diese Schnittstelle ist vollständig nach dem OpenAPI-Standard (Version 3.0) spezifiziert — einer maschinenlesbaren, herstellerneutralen Beschreibung, aus der sowohl eine lesbare Dokumentation als auch Programmcode erzeugt werden kann. Diese Seite erklärt, wo Sie die Spezifikation finden, wie Sie sie öffnen und was Sie damit anfangen können.

Wo die Spezifikation liegt

Die Schnittstellenspezifikation ist Bestandteil jeder Auslieferung der XJustiz-Werkzeuge und liegt im Ordner doc/ des Installationsverzeichnisses — in zwei Formaten mit identischem Inhalt:

Datei Format Geeignet für
doc/xjustiz-tools.html HTML Lesen im Browser — einfach per Doppelklick öffnen, keine weiteren Werkzeuge nötig
doc/xjustiz-tools.yaml YAML (OpenAPI 3.0) Weiterverarbeitung: interaktives Testen, Code-Generierung, Import in API-Werkzeuge

Die Spezifikation gehört immer zur jeweils ausgelieferten Version. Maßgeblich für Ihre Installation ist also die Datei aus Ihrem eigenen Installationsordner — nicht eine Fassung aus dem Netz.

Was die Spezifikation beschreibt

Die Spezifikation dokumentiert jeden Endpunkt der Schnittstelle vollständig: Adresse und HTTP-Methode, alle Parameter, die erwarteten Eingabeformate, Beispiele sowie die möglichen Antworten inklusive Fehlerfälle. Die Endpunkte sind in Funktionsgruppen gegliedert, u. a.:

  • Validate — XJustiz-Nachrichten gegen Schema und Schematron prüfen
  • Convert — Konvertierungen, z. B. XDomea nach XJustiz, XJustiz nach PDF, zwischen XJustiz-Versionen
  • Generate — XJustiz-Nachrichten aus JSON-Eingangsdaten erzeugen (z. B. Schriftgutobjekte, Verfahrensmitteilungen)
  • Health Check — Verfügbarkeit der Anwendung prüfen (z. B. für Monitoring)

Zusätzlich enthält die Spezifikation eine ausführliche fachliche Einführung in die XJustiz-Werkzeuge und ihre Einbettung in den elektronischen Rechtsverkehr.

Wie Sie die Dokumentation nutzen

Nur lesen: die HTML-Datei

Für einen Überblick über die Schnittstelle genügt die Datei doc/xjustiz-tools.html — sie ist eigenständig lauffähig und wird einfach im Browser geöffnet. Sie eignet sich auch zum Weitergeben, etwa an Entwicklerinnen und Entwickler einer Fachanwendung, die die Werkzeuge anbinden sollen.

Interaktiv ausprobieren: Swagger-/OpenAPI-Editor

Mit einem OpenAPI-Editor können Sie die Endpunkte nicht nur lesen, sondern direkt gegen eine laufende Instanz der Werkzeuge aufrufen („Try it out"):

  1. Die XJustiz-Werkzeuge im Demo-Modus starten (siehe Erste Schritte) — im Demo-Modus sind SSL und CORS deaktiviert, sodass Testaufrufe aus dem Browser möglich sind.
  2. Einen Swagger-Editor öffnen — z. B. den Swagger Editor als lokale Installation (Archiv herunterladen, entpacken, index.html im Browser öffnen).
  3. Die Datei doc/xjustiz-tools.yaml über File → Import File laden.
  4. Beim gewünschten Endpunkt „Try it out" wählen, eine Testdatei aus doc/testdaten/ hochladen und die Anfrage absenden — als Server ist bereits http://localhost:8888 hinterlegt.

So lässt sich das Verhalten der Schnittstelle gefahrlos erkunden, bevor eine Zeile Integrations-Code geschrieben ist.

Lokale Installation des Editors empfohlen

Für Tests mit dienstlichen oder echten Daten sollte der Swagger-Editor lokal betrieben werden — beim Online-Editor unter editor.swagger.io würden geladene Dateien den eigenen Rechner verlassen.

In der Fachanwendung nutzen: Code-Generierung

Der größte praktische Nutzen der YAML-Datei: Aus ihr lässt sich mit Werkzeugen wie dem OpenAPI Generator fertiger Client-Code für nahezu jede Programmiersprache erzeugen (Java, C#, TypeScript, Python, …). Die Fachanwendung erhält damit typsichere Aufrufmethoden für alle Endpunkte, ohne dass die HTTP-Kommunikation von Hand programmiert werden muss.

Beispiel für einen Java-Client:

openapi-generator-cli generate -i doc/xjustiz-tools.yaml -g java -o ./xjustiz-tools-client

Auch für andere Zwecke ist die maschinenlesbare Spezifikation der richtige Ausgangspunkt: Import in API-Test-Werkzeuge (Postman, Insomnia, Bruno), Vertrags-Tests in der CI oder automatisierte Schnittstellen-Übersichten im eigenen Betriebshandbuch.

Versionierung der Schnittstelle

Die Schnittstelle folgt der Semantischen Versionierung (SemVer). Sie ist weitgehend unabhängig von fachlichen Anforderungen und bleibt daher voraussichtlich stabiler als die Gesamtanwendung; Breaking Changes werden mit einem Vorlauf von ca. 3–6 Monaten im Changelog angekündigt (siehe Technische Rahmenbedingungen).