DDS Dokumentation

Zugriff mit REST / OpenAPI

Eine externe Applikation kann z.B. Exporte über diese API starten und den Status dieser Exporte dann abrufen.

Hierzu ist eine saubere Authentifizierung, Authorisierung und Schnittstellenimplementierung durch die externe Applikation notwendig.

WARNING

Grundsätzlich ist eine Änderung dieser Schnittstellen bei einem Update vorbehalten, daher ist eine Koordination mit den internen Verantwortlichen für die DDS notwendig, wenn eine Applikation diese Schnittstellen verwenden möchte.

Authentifizierung

DDS bietet grundsätzlich eine Authentifizierung via JWT-Token an für Ihre "Server application" / "confidential client". Diese sind am ADFS konfigurierbar und dann durch Ihre Applikation abrufbar; mit den JWTs kann der Client sich bei DDS authentifizieren.

MS Dokumentation ADFSopen in new window

Beispiel Bearer Token

Authorisierung (Details)

Die aufrufende Applikation läuft in einem Benutzerkontext, für den dann das Bearer-Token zur Authentifizierung ausgestellt wurde. Dieser Benutzer ist am AD wiederum in Gruppen, welche in der DDS die Rollen/Rechte ergeben.

Schnittstellenbeschreibung

Auf der Standard-Landing-Page ist ein Link auf eine HTML-Beschreibung der DDS-OpenAPI-Schnittstelle.

Außerdem können Sie die OpenAPIopen in new window-Beschreibung in YAML-Format abrufen (dds-api-v1.yaml). Aus dieser YAML können Sie mit dem OpenAPI-Generatoropen in new window und ähnlicher Software einen Client für Ihre Programmiersprache generieren lassen.

In der Regel ist ein solcher Generator den manuell geschriebenen Requests vorzuziehen, da sie in der Regel typisierte APIs generieren, die gute Fehlerbeschreibungen und gute Indikatoren für spätere Änderungen der Schnittstelle ermöglichen.

Erste Schritte

  1. Versuchen Sie bitte die Server-Informationen /infoabzurufen. Dies ist auch ohne Authorisierung möglich.
  2. Versuchen Sie bitte die Benutzer-Informationen /login abzurufen. Damit funktioniert auch die Authorisierung.
  3. (falls notwendig) Versuchen Sie den Abruf nach 30 Minuten, 2 Stunden oder 1 Tag noch einmal. Danach wird der ursprüngliche JWT-Token abgelaufen sein und Ihre Applikation muss sich erneut anmelden.

Wenn die obigen Punkte funktionieren, haben Sie alle technisch notwendigen Maßnahmen umgesetzt.

Welche APIs stehen stabil zur Verfügung

"Stabil" heißt hier, dass die Komponentenstruktur in der OpenAPI sich ändern könnte, das übertragene JSON aber kompatibel gehalten wird. Das heißt, es werden möglicherweise weitere Elemente hinzugefügt, aber niemals bestehende umbenannt.

Sofern Änderungen an den stabilen APIs dennoch durchgeführt werden müssen, wird es einen speziellen Hinweis in den Release Notes geben.

Wir behalten uns auch vor, vorhandene Enums um weitere Elemente zu erweitern, was bei strikt typisierten Sprachen mit nativem ENUM-Support unter Umständen nur mit einem Default-Wert gangbar ist.

Pfade

  • /datapoints/{dpid}: Erhalte alle Metadaten eines Datenpunktes und seiner Varietäten identifizierend anhand der DDS-Datenbank-ID des Datenpunktes. Wir überlegen, das "GetDatapointResponse" zu entfernen.
  • /template-jobs/{id}/export: AdHoc - Starten/Triggern eines ExportJobs anhand dessen DDS-Datenbank-ID. Ergibt eine UUID als Token für das Poll.
  • /job/{token}/poll: Aktueller Status eines Job-Runs. Token ist die UUID des Job-Runs. Die Struktur des schedulerStatus könnte in Zukunft möglicherweise angepasst werden.