REST-API¶

Die Basis-URI für jede Anfrage hat die Form http[s]://{host}:{port}/best4automic-rest-v1/api. Die OpenAPI Spezifikation kann über /swagger-ui.html aufgerufen werden.

Ist die Basic-Authentisierung aktiviert, muss der Benutzername mit USERNAME/DEPARTMENT angegeben werden.

Lizenz¶

Zur Überprüfung, ob die RESTful-API korrekt installiert und konfiguriert wurde, kann der Lizenz-Endpunkt aufgerufen werden (GET-Anfrage).

http[s]://{host}:{port}/best4automic-rest-v1/api/license

War der Request erfolgreich, sollte die erworbene Lizenz zurückgegeben werden. Die Antwort sollte beispielsweise so aussehen.

{
  "license": {
    "company": "best-blu consulting with energy GmbH",
    "type": "Production",
    "bundle": "All-in-One",
    "categories": [
      "te",
      "ana",
      "mc",
      "info",
      "util",
      "tp",
      "pm",
      "ta",
      "vcs"
    ]
  },
  "valid": true,
  "message": ""
}

Modul ausführen¶

Zur Auführung eines Moduls muss eine POST-Anfrage an folgenden Endpunkt geschickt werden.

http[s]://{host}:{port}/best4automic-rest-v1/api/module

Bei dieser Anfrage muss ein Body mitgeschickt werden. Dieser muss folgendes Format haben.

{
  "name": "info.Search",
  "options": {
    "connection": "AE12PROD-1000",
    "save-objects": "suchergebnisse.txt",
    "name": "*BEST*"
  }
}

Bei Erfolg gibt es als Antwort den HTTP-Status 202 Accepted zurück. Wie für REST-APIs üblich wird hier also nicht auf das Ende der Ausführung gewartet. Der Status der Ausführung kann mit einer weiteren Anfrage abgefragt werden. Vorweg die Beispielantwort für eine POST-Anfrage.

{
  "id": 1,
  "updated": "2021-06-28T13:39:06.705+00:00",
  "name": "info.Search",
  "status": "INITIATED",
  "returnCode": 0,
  "errorMessage": "",
  "options": {
      "log-flags": [
          "MONOCHROME",
          "TIMESTAMP"
      ],
      "log-variants": [
          "REPORT"
      ],
      "log-datastream-separator": "§§",
      "log-datastream-prefix": "@B4A_STREAM@",
      "recursive": true,
      "folder-ignore-missing": false,
      "log-levels": [
          "ERROR",
          "WARNING",
          "INFO"
      ],
      "parse-processes": false,
      "encryption-key": "server",
      "save-success-only": true,
      "connection": "AE12PROD-1000",
      "end": "2021-06-28 15:39:06",
      "test-mode": false,
      "exclude-list": "/var/lib/tomcat9/webapps/best4automic-rest-v1#api/data/3/exclude-list",
      "search-date": "none",
      "log-error-mode": "never",
      "search-in-vara-type": "text",
      "types": [
          "CALE",
          "CALL",
          "CITC",
          "CLNT",
          "CODE",
          "CONN",
          "CPIT",
          "DASH",
          "DOCU",
          "EVNT",
          "FILTER",
          "FOLD",
          "HOST",
          "HOSTG",
          "HSTA",
          "JOBF",
          "JOBG",
          "JOBI",
          "JOBS",
          "JOBP",
          "JOBQ",
          "LINK",
          "LOGIN",
          "JSCH",
          "SCRI",
          "SYNC",
          "TZ",
          "USER",
          "USRG",
          "VARA",
          "XSL",
          "PRPT",
          "QUEUE",
          "STORE",
          "SLO",
          "PERIOD"
      ],
      "exclude-ignore": false,
      "save-append": false,
      "input-mode": "search",
      "include-links": false,
      "datastream-object-type": false,
      "save-objects": "/var/lib/tomcat9/webapps/best4automic-rest-v1#api/data/3/suchergebnisse.txt",
      "traverse-flows": false,
      "name": "*BEST*",
      "begin": "2021-05-28 15:39:06"
  },
  "_links": {
      "get_module": {
          "href": "http://<host>:<port>/best4automic-rest-v1/api/module/1"
      },
      "get_report": {
          "href": "http://<host>:<port>/best4automic-rest-v1/api/module/1/report"
      },
      "get_output": {
          "href": "http://<host>:<port>/best4automic-rest-v1/api/module/1/output/save-objects"
      }
  }
}

Im unteren Abschnitt der Antwort werden sinnvolle Folgeanfragen aufgelistet. In diesem Fall kann mit der ersten Anfrage der Status und weitere Informationen über den Lauf des Moduls abgefragt werden. Mit der zweiten kann der Report und mit der dritten die Ausgabedatei der Option save-objects geholt werden.

Weitere Anfragen zu diesem Lauf¶

Die GET-Requests sind so abzuschicken, wie sie in der Antwort oben geschickt wurden.

Für die Informationen über die Optionen, den Status oder eventuelle Fehlermeldungen wird diese Anfrage verschickt.

http://<host>:<port>/best4automic-rest-v1/api/module/1

Die Antwort ähnelt stark der POST-Anfrage. In diesem Fall ist das Modul aber bereits erfolgreich durchgelaufen.

{
  "id": 1,
  "updated": "2021-06-28T12:17:40.999+00:00",
  "name": "info.Search",
  "status": "COMPLETED",
  "returnCode": 0,
  "errorMessage": "",
  "options": {
    "all": "options",
    "for": "this",
    "run": "!"
  },
  "_links": {
    "get_report": {
        "href": "http://<host>:<port>/best4automic-rest-v1/api/module/1/report"
    },
    "delete_module": {
        "href": "http://<host>:<port>/best4automic-rest-v1/api/module/cleanup/1"
    }
  }
}

Die Status können sein:

INITIATED: Lauf wurde initialisiert
IN_PROGRESS: Das Modul wurde gestartet, aber noch nicht beendet
COMPLETED: Das Modul wurde erfolgreich beendet
FAILED: Das Modul wurde mit Fehlern beendet. In diesem Fall sind dem returnCode und der errorMessage weitere Informationen zu entnehmen.

Für den Report des Laufs ist folgende Anfrage abzuschicken.

http://<host>:<port>/best4automic-rest-v1/api/module/1/report

Die Ausgabedatei der Option save-objects wird ähnlich abgefragt.

http://<host>:<port>/best4automic-rest-v1/api/module/1/output/save-objects

Abhängig von der Dateiendung, die bei der Post-Anfrage angegeben wurde, wird der Medientyp der Datei geraten und in dem Header der Antwort gesetzt.