API für Drittsysteme – Einsatzverwaltung

Dieser Artikel ist als technische Dokumentation zur Erstellung von Softwarekomponenten, die mit der API interagieren, gedacht. Wie eine bestimmte Integration zu verwenden ist und welche Einstellungen nötig sind, sollte der jeweilige Hersteller dokumentiert haben. Mehr dazu im Abschnitt Bekannte Integrationen.

Motivation

Damit Drittsysteme – also Software von anderen Herstellern aber auch eigene Skripte – automatisiert Aktionen im Plugin ausführen können, ist eine standardisierte Schnittstelle nötig. WordPress bringt seit geraumer Zeit eine REST-API mit, die dafür verwendet werden kann. In der Praxis hat diese allerdings ein paar Nachteile. Das Datenformat ist eng mit dem internen Datenmodell verknüpft und könnte sich somit hin und wieder ändern. Ebenso sind zur Abfrage und Verwendung von Taxonomien (z. B. Fahrzeuge in Einsatzberichten) mehrere Requests nötig.

Deshalb gibt es seit Version 1.10.0 eine Schnittstelle, die speziell diese Probleme umgehen soll. Zum Anlegen eines Einsatzberichts muss nur ein einziger Request abgesetzt werden und das Matching auf bestehende Fahrzeuge, Einsatzarten, usw. geschieht in der Einsatzverwaltung selbst. Ebenso ist das Format der Anfrage vom internen Datenmodell entkoppelt und bleibt somit stabil.

Endpunkte

Die verfügbaren Endpunkte werden auch unter /wp-json/einsatzverwaltung/v1/ inklusive ihrer akzeptierten Methoden und Parameter aufgelistet.

Sollte die Webseite keine pretty Permalinks verwenden, kann stattdessen /?rest_route=/einsatzverwaltung/v1 verwendet werden. Dies gilt auch im Folgenden für die einzelnen Endpunkte.

Nicht alle Webseiten betreiben WordPress direkt unter /, die Seite kann z. B. auch unter https://example.org/wordpress/ laufen. Dabei wären die API-Endpunkte unter /wordpress/wp-json/... bzw. /wordpress/?rest_route=/einsatzverwaltung/... zu finden.

Einsatzbericht anlegen

Der Endpunkt lautet /wp-json/einsatzverwaltung/v1/reports und akzeptiert ausschließlich einen POST-Request. Inhalt des Requests ist ein JSON-Dokument nach folgendem Format:

{
  "reason": "Böschungsbrand",
  "date_start": "2021-09-24T17:14:34+02:00",
  "date_end": "2021-09-24T19:31:41+02:00",
  "content": "Der Beitragstext\nmit Zeilenumbruch",
  "publish": true,
  "location": "A-Dorf",
  "keyword": "B 2",
  "resources": "A-Dorf 10/1,A-Dorf 40/1,A-Dorf 40/2,KBM 2/1"
}

Zwingend nötig sind nur die Felder reason (wird zum Berichtstitel) und date_start (Alarmzeitpunkt).
Die Datumsangaben sind gemäß RFC 3339 zu formatieren.
Der Beitragstext (content) kann Zeilenumbrüche enthalten, jedoch kein HTML.
Ist publish auf true gesetzt, wird der Bericht direkt veröffentlicht (entsprechende Rechte vorausgesetzt). Der Standardwert ist false, wodurch nur ein Entwurf angelegt wird.
Unter keyword wird das Einsatzstichwort angegeben, das intern auf die Einsatzart übersetzt wird. Ist die Einsatzart unbekannt, wird eine neue angelegt.
Der Parameter resources enthält die eingesetzten Einsatzmittel als kommaseparierte Liste. Dabei ist unerheblich ob es sich um eigene oder fremde Einsatzmittel handelt. Unbekannte Einsatzmittel werden ignoriert.

Alternative Bezeichner

Da Einsatzmittel in anderen Systemen unter einem abweichenden Namen geführt sein können, gibt es bei den Fahrzeugen und externen Einsatzmitteln die Möglichkeit, alternative Bezeichner zu hinterlegen. Wird ein Einsatzmittel nicht im ersten Schritt über den Namen gefunden, so werden die alternativen Bezeichner herangezogen.

Die alternativen Bezeichner gibt es ebenso bei den Einsatzarten.

Antwort

Wurde der Einsatzbericht erfolgreich angelegt, antwortet der Server mit Statuscode 201. Inhalt der Antwort ist ein JSON-Dokument mit der ID des Berichts:

{
  "id": 8289
}

Authentifizierung und Berechtigungen

Seit WordPress 5.6 gibt es Anwendungspasswörter, die per Basic Authentication übermittelt werden können. Diese können einerseits manuell im Adminbereich in den Einstellungen des jeweiligen Benutzers erstellt und widerrufen werden. Es gibt aber auch einen Authorization Flow, mit dem ein neu erzeugtes Passwort direkt in die eigene Software übernommen werden kann. Mehr dazu im Integration Guide.

Es wird aber empfohlen, keinen bestehenden Benutzer mit umfangreichen Rechten für API-Anfragen zu verwenden. Stattdessen sollte ein eigener Benutzer mit minimalen Rechten für genau eine Aufgabe angelegt werden.

Die folgenden Benutzerrollen bringt das Plugin bereits mit:

Einsatzberichte-API (Entwürfe): Kann Einsatzberichte per API als Entwurf anlegen
Einsatzberichte-API: Kann Einsatzberichte per API anlegen und ggf. veröffentlichen

Diese Rollen können Benutzerkonten als primäre und einzige Rolle zugewiesen werden. Ein Login in den Adminbereich ist mit diesen Rollen nicht möglich. Siehe dazu auch die Dokumentation zu den Berechtigungen.

Bekannte Integrationen

Diese Softwareprodukte nutzen die API:

Name	Link	Kommentar
Alamos FE2	Dokumentation	Veröffentlicht Berichte direkt, derzeit keine Option für Entwürfe