Schnittstelle: Grundlagen

Diese Seite beschreibt, was für alle Wege der XICBOT-Schnittstelle gilt: Basisadresse und Fassung, Zugangszonen, Aufbau von Anfragen und Fehlern, HTTPS, Antwortköpfe, CORS, seitenweise Abfrage und das Verhalten bei wiederholten Anfragen. Die einzelnen Wege beschreiben die Seiten zu Anmeldung, Integration und den übrigen Bereichen.

Basisadresse und Fassung

Die Schnittstelle liegt unter https://app.xicbot.de/api/. Alle Fachwege tragen die Fassung v1 im Pfad, die Basisadresse für eigene Aufrufe ist also https://app.xicbot.de/api/v1/. Die Anwendung selbst und die Clients aus dem Werkzeugbausatz rufen dieselben Wege auf.

Ob die Schnittstelle arbeitet, zeigt ohne Anmeldung GET /api/v1/public/status. Der Weg meldet nur, ob die einzelnen Teile tragen, und nennt keine weiteren Einzelheiten. Mehr dazu unter Verfügbarkeit und Überwachung.

Eine Anbindung prüfen Sie am einfachsten mit dem Statusweg der Integration. Er ist der einzige Integrationsweg ohne eigenen Bereich und liest keine Daten:

curl https://app.xicbot.de/api/v1/integration/status \
  -H 'Accept: application/json' \
  -H 'X-Api-Key: xbot_…'

Die Antwort nennt das Konto, die Bereiche und den Minutendeckel des Schlüssels. Ihre Felder beschreibt Schnittstelle: Integration, die Deckel Paketsperren und Drosseln.

Zugangszonen

Die Wege unter /api/v1/ sind in Zonen mit eigener Anmeldung gegliedert. Innerhalb einer Zone setzen einzelne Wege zusätzlich eine Rolle, ein Paketmerkmal oder einen Bereich des Schlüssels voraus.

Anfragen

• Schicken Sie Körper als JSON mit Content-Type: application/json und fordern Sie mit Accept: application/json JSON an. So verfährt auch die Anwendung selbst.
• Dateien, etwa für eine Wissensquelle vom Typ file, gehen als multipart/form-data. Den Kopf Content-Type setzt dabei Ihr HTTP-Client samt Trennmarke; ein von Hand gesetzter Kopf ohne Trennmarke macht den Körper unlesbar.
• Unter /api/ antworten Fehler auch ohne Accept-Kopf als JSON, nicht als HTML-Seite.
• Wege der Anwendung melden sich mit Authorization: Bearer <Marke> an, die Integration mit dem Kopf X-Api-Key. Steht ein Schlüssel in der Adresse (?api_key= oder ?key=), lehnt die Integration die Anfrage mit 400 und key_in_url ab. Details stehen unter Anmeldung.
• Zeitpunkte gibt die Schnittstelle als Zeichenkette nach ISO 8601 aus, etwa im Feld created.
• Antworten eines Assistenten, etwa auf POST integration/chat, kommen als Datenstrom mit Content-Type: text/event-stream. Fehler, die vor dem Start feststehen, kommen als JSON mit passendem Status. Läuft der Strom bereits, steht ein Fehler als Ereignis im Strom, und der Status ändert sich nicht mehr. Der Python-Client aus dem Werkzeugbausatz fordert solche Antworten mit Accept: text/event-stream an.
• Der Webserver bricht eine Anfrage ab, wenn die Anwendung 300 Sekunden lang keine Daten liefert. Stellen Sie die Zeitgrenze Ihres Clients für lange Antworten entsprechend ein.

Fehlerformat

Fehler kommen als JSON mit passendem HTTP-Status. Je nach Herkunft hat der Körper eine von fünf Formen:

Bei einem unerwarteten Fehler mit Status 500 oder höher ersetzt die Schnittstelle den Text in message durch „Serverfehler“ und entfernt die Felder exception, file, line und trace. Eine Antwort ohne message bekommt dabei keine. Der Text einer Meldung mit Status 400 bis 499 bleibt erhalten, einschließlich der Feldfehler.

Statuscodes und Kennzeichen

Unbekannte Adressen und falsche Methode

Einen Aufruf, zu dem es keinen Weg gibt, beantwortet ein Auffangzweig mit JSON statt mit einer HTML-Fehlerseite. Er greift unter /api/ für GET, HEAD, POST, PUT, PATCH und DELETE, auch außerhalb von /api/v1/: /api/ selbst und jede erfundene Adresse antworten mit 404 und route_unknown.

Gibt es den Pfad, aber nicht für die verwendete Methode, antwortet die Schnittstelle mit 405 und method_not_allowed. Das Feld allowed listet die erlaubten Methoden alphabetisch, ohne HEAD. OPTIONS beantwortet der Auffangzweig nicht, damit Vorabfragen fremder Ursprünge bei der CORS-Schicht bleiben.

curl -s https://app.xicbot.de/api/v1/login -H 'Accept: application/json'
{"error":"method_not_allowed","allowed":["POST"]}

curl -s https://app.xicbot.de/api/v1/beispiel -H 'Accept: application/json'
{"error":"route_unknown"}

HTTPS und HSTS

Die Schnittstelle arbeitet über HTTPS. Anfragen über http unter /api/ leitet der Webserver mit 301 auf die https-Adresse um, gleich mit welcher Methode. Erreicht eine unverschlüsselte Anfrage dennoch die Anwendung, leitet diese nur GET und HEAD mit 301 um und lehnt alle anderen Methoden mit 403 und https_required ab. Das Umleitungsziel baut die Anwendung aus der eigenen Adresse, nicht aus dem Host-Kopf der Anfrage.

Antworten über https tragen Strict-Transport-Security: max-age=31536000; includeSubDomains. Browser rufen die Adresse damit ein Jahr lang nur noch über https auf. preload ist bewusst nicht gesetzt.

Antwortköpfe

CORS

CORS-Köpfe setzt die Schnittstelle nur auf der öffentlichen Strecke /api/v1/public/*, etwa für Statusseite, Änderungsprotokoll und Widget-Zweig, und nur für die zugelassenen Ursprünge aus der Tabelle. Die Integration und die Wege mit Anmeldung setzen keine CORS-Köpfe. Rufen Sie die Integration darum von Ihrem Server auf, nicht aus Javascript im Browser.

Eine eigene Regel gilt für GET cart/pickup/{token}. Der Weg ist für den Abruf von Server zu Server gedacht. Im Browser darf nur der Ursprung der hinterlegten Übergabeadresse die Antwort lesen. Die Antworten tragen Cache-Control: no-store und Vary: Origin.

Da nur Content-Type und Accept zugelassen sind, lässt eine Vorabfrage aus einem fremden Ursprung weder X-Api-Key noch Authorization zu. Die Wege für das Chatfenster beschreibt Widget-Wege, die übrigen öffentlichen Wege Öffentliche Wege.

Seitenweise Abfrage

Listen liefert die Schnittstelle seitenweise über den Abfrageparameter page, beginnend bei 1. Seitengröße, Spannen und Rückgabefelder unterscheiden sich je Weg. Wo ein Weg eine Spanne prüft, ergeben Werte außerhalb davon 422; die Integration wertet Werte unter 1 als 1.

Wiederholte Anfragen

Doppelungen verhindert die Schnittstelle über Kennungen im Körper oder über den Zustand des Datensatzes, nicht über einen eigenen Kopf. Ob sich eine Anfrage nach einem Abbruch schadlos wiederholen lässt, hängt vom Weg ab:

Häufige Fragen