OpenAPI-Beschreibungsdatei
Sie können mit der HTTP REST API von RaptorXML+XBRL Server über ein OpenAPI-Dokument interagieren. Mit Hilfe dieses Dokuments erfahren Sie nicht nur, welche Funktionalitäten die HTTP REST API enthält und wozu diese dienen, sondern können auch spezifische HTTP Requests testen, bevor Sie Code generieren, der diese Requests implementiert.
Ihre Installation von RaptorXML+XBRL Server enthält eine OpenAPI-Dokumentdatei im YAML-Format, die Sie ausprobieren oder erweitern können. Diese Datei befindet sich im Verzeichnis Examples-Ihrer RaptorXML+XBRL Server-Installation. Unter Windows lautet der Dateipfad: C:\Programme\Altova\RaptorXMLXBRLServer2026\examples\raptorxbrl_http_rest_api.yaml. Auf Linux-Systemen liegt sie im Ordner RaptorXML+XBRL Server Examples.
OpenAPI-Dokument im Swagger-Editor
Durch Öffnen der OpenAPI-Beispieldokumentdatei (siehe oben) im Swagger-Editor (Abbildung unten) können Sie mit der HTTP API von Raptor interagieren und Requests an die HTTP API senden. Im linken Bereich des Editors sehen Sie die den YAML-Code der Beschreibungsdatei und im rechten Bereich die vom Swagger-Editor generierte interaktive Schnittstelle. Wenn Sie den Code im linken Bereich bearbeiten, werden die Änderungen sofort im rechten Bereich angezeigt. Über die interaktive Schnittstelle können Sie die Daten von HTTP Requests eingeben, diese Requests ausführen und die Anwort des Servers anzeigen. Im Abschnitt Client Requests ist der Mechanismus beschrieben, wie Requests an die HTTP API von RaptorXML+XBRL Server gesendet und Antworten (Responses) empfangen werden.
Herstellen einer Verbindung zum Server
Um sich mit RaptorXML+XBRL Server über seine HTTP API zu verbinden, müssen Sie die Adressdaten des Server-Rechners, auf dem RaptorXML+XBRL Server gehostet wird, eingeben. Dies können Sie entweder über den YAML-Code der OpenAPI-Datei oder über die entsprechenden Dateneingabefelder im rechten Bereich (siehe Abbildung oben) tun. Die Standard-Server-Adresse in der OpenAPI-Datei lautet localhost:8087.
Anmerkung: Stellen Sie sicher, dass der RaptorXML+XBRL Server-Dienst gestartet wurde (Windows, Linux), bevor Sie Ihre HTTP Requests senden.
Durch Senden eines GET / version Request können Sie testen, ob die Verbindung korrekt ist. Dies ist der erste Request in der Beschreibungsdatei (Abbildung unten). Klicken Sie im rechten Bereich zuerst auf Try it out und anschließend auf Execute.
Die Versionsinformationen werden im Abschnitt Responses des GET Request-Kästchens angezeigt (siehe Abbildung oben). Wenn Sie einen Fehler erhalten, können Sie die Response löschen, den Fehler beheben und den Request erneut ausführen. Häufige Fehler sind eine fehlgeschlagene Verbindung, was möglicherweise daran liegt, dass RaptorXML+XBRL Server nicht korrekt gestartet wurde oder nicht lizenziert ist.
Posten eines Request mit POST, Abrufen der Server-Antwort mit GET
Um einen HTTP Request zu senden, gehen Sie folgendermaßen vor. Klicken Sie im rechten interaktiven Bereich auf die Schaltfläche Try it out der POST /queue-Methode und geben Sie im Eingabefeld msg Ihren POST Request ein (siehe Abbildung unten). So haben wir z.B. in der Abbildung unten einen Request für den Befehl valxml-withxsd (xsi) eingegeben, um die Gültigkeit der Datei NanonullOrg.xml zu überprüfen:
{
"command": "xsi",
"options": {
"verbose": true
},
"args": [
"file:///C:/Test/OpenAPI/NanonullOrg.xml"
]
}
Wir müssen die XSD-Datei nicht bereitstellen, da die XML-Datei einen Verweis auf die XSD-Datei enthält. (Die XML-Datei und die davon referenzierten XSD-Dateien befinden sich im Ordner Examples des RaptorXML+XBRL Server-Installationsordners, doch haben wir diese in einen separaten Arbeitsordner kopiert, siehe URL in der Abbildung.)
Nähere Informationen zur Syntax einer Nachricht finden Sie unter Initiieren von Aufträgen mittels POST. Informationen über die verschiedenen in RaptorXML+XBRL Server verfügbaren Befehle finden Sie unter Befehlszeilenschnittstelle (CLI).
Klicken Sie, nachdem Sie die Nachricht des Request eingegeben haben, auf Execute. Die Server-Antwort, die eine Auftrags-ID und ein Auftragsergebnisdokument enthält, wird unmittelbar unterhalb des Request angezeigt und sieht ungefähr so aus wie in der Abbildung unten.
Sie können das Ergebnisdokument überprüfen, um die Einzelheiten der Server-Antwort zu sehen. Mit Hilfe des GET /results/{jobId} Request können Sie die URI des Ergebnisdokuments abrufen. Alternativ dazu erhalten Sie die URI, indem Sie den "result"-Teil der Server-Antwort (siehe Abbildung oben) an die Server-Adresse anhängen (z.B. http://localhost:8087/).
Nähere Informationen zu Server-Antworten finden Sie in den Kapiteln Server-Antwort auf den POST Request, Abrufen des Ergebnisdokuments und Abrufen von Fehler-/Meldungs-/Ausgabedokumenten.
Andere HTTP Requests
Sie können auch andere in der OpenAPI-Datei definierte HTTP Requests verwenden. In der Abbildung unten sehen Sie die verfügbaren Requests. Beachten Sie, dass RaptorXML+XBRL Server-Funktionalitäten mittels POST angefordert werden. Mit Hilfe der folgenden GET Requests können Sie die verschiedenen Ergebnisdokumente, darunter Ausgabe- und Fehlerdokumente abrufen.
Der Pfad nach der jeweiligen Methoden-Schaltfläche ist der Pfad, der an {Serveradresse}/v1 angehängt wird. Wenn die Serveradresse z.B. http://localhost:8087 ist, lautet der vollständige Pfad einiger Requests, wie unten angegeben. Beachten Sie, dass Parameter in geschweiften Klammern im Request angegeben werden müssen.
GET /version
http://localhost:8087/v1/version
GET /results/{jobId}
http://localhost:8087/v1/results/{jobId}
wobei
{jobId} die vom Server bei Empfang eines Request über die POST-Warteschlange zurückgegebene Auftrags-ID ist. Wenn Sie diese Auftrags-ID in den GET /results Request eingeben, gibt der Server die URI des Ergebnisdokuments zusammen mit seiner eigenen Auftrags-ID (der SubJob ID) zurück.
GET /results/{subJobId}/output/{fileName}
http://localhost:8087/v1/results/{subJobId}/output/{fileName}
wobei
{subJobId} die vom Server bei Ausführung des GET /results Request zurückgegebene Auftrags-ID ist.
{fileName} der Name einer Ausgabe- oder Fehlerdatei ist, die bei Ausführung eines GET /results Request zurückgegeben wurde. Nähere Informationen dazu finden Sie unter Abrufen von Fehler-/Meldungs-/Ausgabedokumenten.