BeeCollect API: Header-Format und Authentifizierung

Die Authentifizierung erfolgt bei der BeeCollect API grundsätzlich über HTTP Basic Authentication. Die Benutzerangaben müssen dabei bei jedem Request übermittelt werden, denn die API liefert gemäß dem REST-Standard keinerlei Session-Informationen.

Ein typischer HTTP-Header für einen GET-Request (lesende Abfrage) sieht zum Beispiel so aus:

Host: localhost:11077
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:43.0) Gecko/20100101 Firefox/43.0
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Connection: keep-alive
 

Ein typischer, von der API gesendeter Antwort-Header für einen GET-Request könnte dann so aussehen:

Connection: closed
Content-Length: 43
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Jan 2016 07:14:36 GMT
Server: BeeCollectAPI/1.0
 

Definition des Ausgabeformates

Über den Header-Eintrag Accept wird Format für das Abfrageergebnis festgelegt. Unterstützte Formate sind hier bei Datenabfragen:

  • application/json: Ausgabe als JSON-Struktur
  • application/xml: Ausgabe als XML-Struktur

Die Angabe eines Encodings ist dabei nicht notwendig, alle Abfrageergebnisse werden immer als UTF-8 geliefert.

Bei der Abfrage von Bildern und Binärdaten werden darüber hinaus noch folgende Formate unterstützt:

  • image/jpeg: Ausgabe als JPEG (Base64- oder Binärdaten)
  • application/octet-stream: Ausgabe als unverschlüsselte, unkomprimierte Binärdaten

Bei der Ausgabe von Bildern kann über den HTTP-Header-Parameter Accept-encoding gesteuert werden, ob die Daten als unkomprimierte Binärdaten oder als Base64-codierter Datenstrom gesendet werden.

Authentifizierung

Jede Abfrage muss zwingend einen Header-Eintrag Authorization enthalten, der entsprechend der HTTP-Spezifikation die Benutzerangaben enthält. Benutzer und Kennwort werden dabei in der Form user:password als Base64-kodierter String gemeinsam mit dem Schlüsselwort Basic übergeben.

Fehlt im Header ein entsprechender Eintrag, antwortet die API mit dem Response-Code 401 (Not Authorized).