Zum Hauptinhalt springen

REST API

Mithilfe des Bubble Chat REST API kann die Wissensdatenbank verwaltet werden, ohne direkt auf das CMS zugreifen zu müssen. Über diese Schnittstelle wird das Anlegen, Aktualisieren und Löschen von Wissenseinträgen ermöglicht, sodass das Verwalten von Inhalten automatisiert oder in eigene Workflows integriert werden kann.

Im Folgenden wird beschrieben, wie das REST API genutzt werden kann, welche Endpunkte zur Verfügung stehen und auf welche Weise Authentifizierung sowie Fehlermanagement erfolgen. Sämtliche Methoden werden in der Swagger-Dokumentation detailliert erläutert.

Voraussetzungen​

  1. Access Token: Ein gültiges Access Token wird von Apptiva bereitgestellt und ist für die Authentifizierung erforderlich.
  2. API-Endpunkt: Die Basis-URL der API muss bekannt sein (z. B. https://<CHATBOT-DOMAIN>/cms/api/v1/).

API Spezifikation​

Alle API Funktionen sind in einer interaktiven Swagger-Dokumentation beschreiben. Diese steht unter dem Pfad https://<CHATBOT-DOMAIN>/cms/api/docs/ zur Verfügung.

In der Swagger-Dokumentation können:

  • Alle Endpunkte aufgelistet und eingesehen werden.
  • Beispielanfragen inklusive Request- und Response-Beispielen betrachtet werden.
  • Parameter und Datentypen detailliert überprüft werden.
  • Testaufrufe direkt in der Oberfläche ausgeführt werden.

Zusätzlich kann die Schnittstellendefinition im OpenAPI-Format (YAML oder JSON) direkt heruntergeladen werden:

  • OpenAPI YAML: https://<CHATBOT-DOMAIN>/cms/api/docs/swagger.yaml
  • OpenAPI JSON: https://<CHATBOT-DOMAIN>/cms/api/docs/swagger.json

Es wird empfohlen, stets mit der Swagger-Dokumentation zu beginnen, um einen Überblick über die verfügbaren Funktionen und die benötigten Felder zu erhalten.

Übersicht der Funktionen​

Das REST API stellt im Wesentlichen folgende Funktionen zur Verfügung:

  • Wissensdatenbanken suchen, erfassen, ändern und löschen
  • Einträge einer Wissensdatenbank suchen, hinzufügen, ändern und löschen
  • Dokumente zu einem Wissensdatenbankeintrag hinzufügen, ändern und löschen

Mit diesen Kernfunktionen wird der komplette Lebenszyklus von Wissenseinträgen und zugehörigen Dateien abgedeckt, was eine flexible Integration in bestehende Systeme ermöglicht.

Authentifizierung und Sicherheit​

Die Authentifizierung erfolgt mittels eines Access Tokens, das von Apptiva bereitgestellt wird. Das Token wird als Bearer Token im Authorization-Header mitgegeben, um jede Anfrage zu legitimieren. Ein Beispiel für die Übergabe dieses Tokens lautet:

Authorization: Bearer <ACCESS-TOKEN>

Beispielaufrufe​

Im Folgenden werden einige typische Beispiele mit curl vorgestellt. Dabei sollten <CHATBOT-DOMAIN> und <ACCESS-TOKEN> durch die entsprechenden Werte ersetzt werden.

Erstellen einer Wissensdatenbank​

curl -X 'POST' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Confluence",
  "conditions": {
    "language": "DE",
    "contexts": ["LOGGED_IN_USER"]
  }
}'

Aktualisieren eines Wissenseintrags​

curl -X 'PUT' \
  'http://localhost:3000/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/entries/<ID-DES_WISSENSEINTRAGS>' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Release notes version 3.42",
  "uri": "https://my.confluence.com/kb/2343",
  "sections": [
    "Version 3.42 ermöglicht nun die Benutzer-Authentifizierung via SAML und erleichtert dadurch die nahtlose Einbindung in bestehende Identity-Provider-Lösungen."
  ]
}'

Dokument zu einem Wissenseintrag hinzufügen​

curl -X 'POST' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/entries/<ID-DES_WISSENSEINTRAGS>/attachments' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'origin=https://my.confluence.com/kb/2343/attachments/release-news.pdf' \
  -F 'file=@release-news.pdf;type=application/pdf'

Oder mit JavaScript

const fileInput = document.getElementById("fileInput");
const file = fileInput.files[0];

const formData = new FormData();
formData.append(
  "origin",
  "https://my.confluence.com/kb/2343/attachments/release-news.pdf"
);
formData.append("file", file, "release-news.pdf");

fetch(
  "https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/entries/<ID-DES_WISSENSEINTRAGS>/attachments",
  {
    method: "POST",
    headers: {
      accept: "application/json",
      Authorization: "Bearer <ACCESS-TOKEN>",
    },
    body: formData,
  }
);

Fehlerbehandlung​

Bei fehlerhaften Anfragen wird üblicherweise ein HTTP-Statuscode zurückgegeben, der auf die Art des Fehlers hinweist. Übliche Statuscodes sind:

  • 400 Bad Request: Die Anfrage konnte nicht verarbeitet werden (z. B. falsche JSON-Struktur).
  • 401 Unauthorized: Es wurde kein Access Token mitgegeben.
  • 403 Forbidden: Das übermittelte Access Token hat keine Berechtigung.
  • 404 Not Found: Die gewünschte Ressource existiert nicht.
  • 413 Content Too Large: Das übermittelte Dokument (Attachment) ist zu gross.
  • 415 Unsupported Media Type: Der Typ des übermittelten Dokuments (Attachment) wird nicht unterstützt.
  • 500 Internal Server Error: Ein unerwarteter Serverfehler trat auf.