Benutzer-Werkzeuge

Webseiten-Werkzeuge


rest_api

REST API

Das REST API bietet ausschließlich eine generelle Authentisierung ohne Zugriffssteuerung für einzelne Benutzer. Auf das API kann über das Rest Interface zugegriffen werden. Es dient ausschließlich dazu, Requests der REST Frontends zu verarbeiten.

Durchführung einer Suchanfrage

Suchanfragen dienen zur Suche nach archivierten E-Mails. Da alle E-Mails incl. ihrer Attachements volltext-indexiert vorliegen, können E-Mails anhand jeden beliebigen Inhalts bzw. anhand jedes beliebigen Merkmals (und selbstverständlich auch beliebiger Kombinationen von Merkmalen) gefunden werden.

Suchanfragen werden mittels eines HTTP bzw. HTTPS URL aufgerufen. Die Syntax ist dabei grundsätzlich:

http://bennohost:21080/search/{suchanfrage} 

Der dem Keyword „search“ folgende Slash (/) ist dabei obligatorisch. Die Suchanfrage selbst setzt sich aus mehreren Parametern zusammen. Diese werden in der üblichen Form in dem URL codiert:

?option1=wert1&option2=wert2&option3=wert3 

Die vollständige Suchanfrage hat damit folgendes Format:

http://bennohost:21080/search/?option1=wert1&option2=wert2... 

Syntaxbeispiel für Suchanfragen

Hinweis: Die URLs werden aus drucktechnischen Gründen teilweise mehrzeilig dargestellt. Sie sind jedoch ohne Leerzeichen usw. in einer Zeile anzugeben!

Hier zunächst die syntaktische Darstellung von Suchanfragen. Weiter unten sind konkrete Beispiele für Suchanfragen abgebildet.

Die Query Syntax

Suchanfragen werden in Benno MailArchiv grundsätzlich in der Query-Syntax von Apache Lucene verfasst. Die vollständige Syntax von Lucene kann bspw. in den nachstehenden Quellen nachgelesen werden:

Minimale Suchanfrage

http://bennohost:21080/search/?archive=container-identifier&query=suchanfrage

Beispiel mit cURL:

curl -u benno2:<shared secret> \
  --data archive=BennoContainer \
  --data 'query=Text:hallo' \
  --data 'filterQuery=(*)' \
  --data start=0 \
  --data limit=20 \
  -D - -k http://localhost:21080/search/

Suchanfrage mit Filterung

http://bennohost:21080/search/?archive=container-identifier&filterQuery=filter&query=suchanfrage

Die Verwendung von Filtern in Suchanfragen kann zu effizienterem Verarbeiten der Abfragen führen. Die Verarbeitungsreihenfolge in Lucene ist dabei:

zunächst Ausführung der „query“, danach Filterung der Ergebnisliste mit der „filterQuery“.

Hinweis: Alle (auch komplexe) Suchanfragen können als „query“ gestaltet werden. Die Filterung kann bspw. ergänzend verwendet werden, um die Menge der Suchergebnisse auf E-Mails mit bestimmten Merkmalen einzugrenzen. Bspw. werden alle Suchanfragen der Benno MailArchiv WebApp über „query“ abgebildet, während die Benutzerberechtigungen durch Filter („filterQuery“) abgebildet werden.

Parameter einer Suchanfrage

Pflichtparameter

Eine Suchanfrage setzt sich aus mindestens folgenden Parametern zusammen:

  • archive: eindeutiger Identifier des Containers, in dem die Suche erfolgen soll
  • query: Die eigentliche Suchanfrage
  • filterQuery: Filterkriterien, die nach der Suche auf das Suchergebnis angewendet werden

Optionale Parameter

Suchanfragen können neben den o.g. Pflichtparametern zusätzlich folgende optionale Parameter enthalten:

  • start: Nummer des ersten auszugebenden Ergebnis-Elements (Standard: 1) (1..n)
  • limit: Anzahl der auszugegebenen Elemente des Ergebnisses (Standard: 20)
  • sort: Attribut, nach dem die Trefferliste sortiert werden soll (Standard: „sent“ (Sendedatum))
  • sortAsc: Sortierung aufsteigend (Standard: false)
  • full: Ausgabe aller Attribute der Maildokumente (Standard: false)

Rückgabewerte einer Suchanfrage

  • Resultatwerte (HTTP-Fehlercodes der Suchoperation):
    • 1xx - Information
    • 2xx - OK …
    • 3xx - Aufforderungen
    • 4xx - Temporäre Fehler
    • 5xx - Dauerhafte Fehler
  • Resultatdaten (Suchergebnisse bzw. Trefferlisten):
  • limit: wie aus den Parametern, oder die Defaultwerte
  • found: Anzahl der gefundenen E-Mails
  • first: Stelle im Suchergebnis der ersten ausgegebenen Zeile (1..n, 0 falls keine Zeile ausgegeben wurde)
  • last: Stelle im Suchergebnis der letzten ausgegebenen Zeile (1..n, 0 falls keine Zeile ausgegeben wurde)
  • count: Anzahl der Zeilen in dieser Rückgabe
  • results: Trefferliste; Array mit JSON Objekten mit dem folgenden Aufbau:
  • from: Absenderadresse
  • to: Zieladressen
  • multipart: 1 wenn Mehrteilig, 0 wenn nicht
  • subject: Betreff
  • summary: Zusammenfassung
  • sent: das Absendedatum
  • id: eindeutige ID der archivierten E-Mail (notwendig, um diese aus dem Archiv abrufen zu können)

Beispiele für Suchanfragen

Allgemeines

Die nachfolgenden Beispiele für Suchanfragen beginnen alle mit dem folgenden HTTP URL. Dieser URL wird in den Beispielen nicht weiter extra aufgeführt.

http://bennohost:21080/search/ 

Weiterhin ist zu beachten, dass die Suchanfragen grundsätzlich einzeilig sind, auch wenn sie nachstehend oft mehrzeilig dargestellt werden!

BASIC AUTH durch Übergabe von Benutzer und Shared Secret über den URL

Wie bereits eingangs erwähnt, raten wir ausdrücklich dazu, diese Form der Autorisierung nicht in browser-basierten Web-Anwendungen einzusetzen, da das Shared Secret im Klartext in der URL enthalten ist bzw. im Browser nachgelesen werden kann!

http://benno2:shared-secret@localhost:21080/search/... 

Minimale Suchanfrage

?archive=BennoContainer&query=(Sender:*hansen-und-meyer*) 

In dieser Suchanfrage werden alle E-Mails im Standard-Container2 gesucht, die von Absenderadressen stammen, in denen das Literal „hansen-und-meyer“ vorkommt.

Suchanfrage mit zwei Suchkriterien, per UND verknüpft

?archive=BennoContainer&query=((Sender:*hansen-und-meyer*)) AND (Recipient:vertrieb@*))

In dieser Suchanfrage werden alle E-Mails im Standard-Container gesucht, die von Absenderadressen stammen, in denen das Literal „hansen-und-meyer“ vorkommt UND deren Empfängeradressen das Literal „vertrieb@“ enthalten.

Suche in einem Zeitraum

?archive=BennoContainer&query=((Sender:*hansen-und-meyer*) AND (Date:[201308231020 TO 201308271605]))

Hier werden die E-Mails im Zeitraum zwischen 23.08.2013 10:20 und dem 27.08.2013 um 16:05 gesucht.

Suchanfrage mit Filterung

?archive=BennoContainer&filterQuery=(Recipient:vertrieb@*)&query=(Sender:*hansen-und-meyer*)

Bei dieser Suchanfrage werden ebenfalls alle Mails gesucht, deren Absenderadresse das Literal „hansen-und-meyer“ enthält. Anschließend werden die Ergebnisse gefiltert. Es werden alle E-Mails ausgefiltert, deren Empfängeradressen nicht „vertrieb@“ enthalten.

Wie gesehen, führen beide Wege zum gleichen Ergebnis.

Suchanfrage mit zwei Suchkriterien, per ODER verknüpft

?archive=BennoContainer&query=((Sender:*hansen-und-meyer*)) (Recipient:vertrieb@*))

In dieser Suchanfrage werden alle E-Mails im Standard-Container gesucht, die von Absenderadressen stammen, in denen das Literal „hansen-und-meyer“ vorkommt ODER deren Empfängeradressen das Literal „vertrieb@“ enthalten.

Suchkriterien

Neben den Suchkriterien für Sender bzw. Recipient stehen weitere Suchkriterien zur Verfügung. Eine Liste aller Suchkriterien befindet sich im Anhang dieser Dokumentation (siehe Abschnitt „Suchkriterien in Suchabfragen“).

Hinweis: Alle Suchkriterien können in Suchanfragen in beliebiger Form (UND, ODER) und in beliebiger Reihenfolge miteinander kombiniert werden.

API-Call: Zugriff auf eine E-Mail im Archiv

Der API-Call zum Zugriff auf eine archivierte E-Mail dient dazu, eine E-Mail (incl. etwaiger Attachements) aus dem Archiv zu holen. Da jede E-Mail im Archiv eindeutig identifiziert ist, erfolgt der Zugriff über diesen eindeutigen Identifyer.

Syntaxbeispiel für den Abruf einer E-Mail aus dem Archiv

Hinweis: Die URLs werden aus drucktechnischen Gründen teilweise mehrzeilig dargestellt. Sie sind jedoch ohne Leerzeichen usw. in einer Zeile anzugeben!

Hier zunächst die syntaktische Darstellung eines Abrufs. Weiter unten sind konkrete Beispiele für das Abrufen von E-Mails abgebildet.

Der Aufruf erfolgt analog der zu Suchanfragen als HTTP URL. Die Syntax ist dabei grundsätzlich:

http://bennohost:21080/mail/?archive=container-identifier&id=id 

Parameter für den Abruf einer E-Mail aus dem Archiv

Pflichtparameter

Der Abruf einer E-Mail setzt sich aus den beiden folgenden Parametern zusammen:

  • archive: eindeutiger Identifier des Containers, aus dem die E-Mail gelesen werden soll
  • id: Der eindeutige Identifyer der E-Mail (ID) incl. der Bezeichnung der Box im Container - Format <box»<mailid>

Optionale Parameter

Die aus dem Archiv gelesene E-Mail wird standardmäßig als JSON Objekt an das aufrufende Programm zurückgegeben. Mittels der Option format kann die Rückgabe der E-Mail im „raw“ Format, also RFC 822 bzw. RFC 2822 (Plaintext) erzwungen werden.

  • format=raw - E-Mail im RFC-822 Format anfordern
  • skipUTF8Recode=true - E-Mail im Orginal zurück geben
  • header=true - Secret Header zurück geben

Achtung! Um eine E-Mail aus dem Repo zum Re-Indexieren ist es erforderlich, die E-Mail ohne Anpassung des Encodings zu laden. Daher ist hier der Parameter skipUTF8Recode=true zwingend erforderlich.

Rückgabewerte eines Abrufs einer E-Mail aus dem Archiv

Resultatwerte (HTTP-Fehlercodes der Suchoperation):

  • 1xx - Information
  • 2xx - OK …
  • 3xx - Aufforderungen
  • 4xx - Temporäre Fehler
  • 5xx - Dauerhafte Fehler

Syntaxbeispiel für den Abruf eines Attachments einer E-Mail im Archiv

Ein Attachment kann über den Dateinamen oder über die Attachment-Id referenziert werden.

http://bennohost:21080/attachment/?archive=container-identifier&id=id&attachment=Dateiname
http://bennohost:21080/attachment/?archive=container-identifier&id=id&attachmentId=0

Pflichtparameter

  • archive: eindeutiger Identifier des Containers, aus dem die E-Mail gelesen werden soll
  • id: Der eindeutige Identifyer der E-Mail (ID) incl. der Bezeichnung der Box im Container - Format <box»<mailid>
  • attachment: Dateiname des Attachments
  • attachmentId: Id des Attachments wie in der Liste der Attachments angegeben.

Beispiele für den Abruf von Mails aus dem Archiv

http://localhost:21080/mail/?archive=BennoContainer&id=2012:1C6626F53B0B...67ADA0 FB4E

Dieser Abruf liest die E-Mail mit der eindeutigen ID „1C6626F53B0B...67ADA0 FB4E“ aus dem Archiv und gibt sie an das aufrufende Programm zurück. Die E-Mail wird dabei aus der Box „2012“ des Containers „BennoContainer“ gelesen.

Suchkriterien in Suchanfragen

E-Mails können anhand aller indexierten Inhalte gesucht werden. Die Suchkriterien können einzeln oder mit den logischen Operatoren „UND“ bzw. „ODER“ kombiniert werden. Details zur Syntax siehe oben und in der einschlägigen Dokumentation zu Apache Lucene im Internet (URLs siehe oben).

Folgende Suchkriterien stehen über die API für Suchanfragen zur Verfügung:

  • Date: Datum der E-Mail
  • From: Absenderadresse der E-Mail
  • Recipient: Empfängeradressen (beinhaltet To, Cc und Bcc)
  • RecipientDomain: Domäne des Empfängers
  • Sender: Absenderadresse der E-Mail
  • SenderDomain: Domäne des Absenders
  • Size: Größe der E-Mail
  • Subject: Betreffzeile der E-Mail
  • To: To-Empfängeradressen
  • hasAttachment: E-Mail mit Attachement
  • id: Eindeutige ID der E-Mail im Archiv
  • Cc: Cc-Empfängeradressen
  • Text: Suche nach Wörtern im Text der E-Mail (incl. Text aus den Attachements)
  • HEADER-XYZ: Mailheader „XYZ“ enthält einen bestimmten Wert (der Name des Header muss in GROßBUCHSTABEN geschrieben werden)

Rückgabe der Ergebnisse einer Suchanfrage

Die nachstehend aufgeführte Suchanfrage ergibt bspw. eine Ergebnismenge von 2 gefundenen E-Mails:

http://bennohost:21080/search/?archive=BennoContainer&query=(Sender:*hansen-und-meyer*)

Das Suchergebnis (2 Treffer) wird in Form von JSON Objekten zurückgegeben und hat bspw. folgenden Inhalt:

{ 
  "licenseValid":true, 
  "limit":2, 
  "results" 
    { 
      "id":"2012:748B034C4AF3004231D24B9DE2515822AB16485914AB3AE055C40DA336F4272F00", 
      "Subject":"Re: Anfrage bezüglich Partnerschaft", 
      "Date":"201206191122", 
      "hasAttachment":"1", 
      "To":["W. Robert" <w.robert@robert-druck.de>], 
      "Bcc":[], 
      "Cc":[], 
      "From":"info@hansen-und-meyer.de" 
    }, 
    { 
      "id":"2012:1C6626F5E02E1B3B0B74DE794BC67408A64484C8B8B98A83C130162B077AD6AB00", 
      "Subject":"Re: Anfrage bezüglich Partnerschaft", 
      "Date":"201206191122", 
      "hasAttachment":"1", 
      "To":["w.robert@robert-druck.de"], 
      "Bcc":[], 
      "Cc":[], 
      "From":"info@hansen-und-meyer.de" 
    } 
  ], 
  "last":1, 
  "count":2, 
  "overall":25, 
  "first":0, 
  "found":14 
}

Aufbau der Ergebnisliste

Bei einer Suche wird ausschließlich auf den Index von Benno MailArchiv zugegriffen. Alle hier aufgeführten Werte entsprechen direkt dem Inhalt des Indexes, während eine E-Mail bei der Anzeige aus dem Repo gelesen und für die Anzeige gesondert geparst wird.

Zeitstempel (Date)

Beim Indexieren wird der Zeitstempel aus dem Date-Header in die Zeitzone UTC konvertiert und in das entsprechende Index-Feld geschrieben. Bei Anzeige einer E-Mail wird dieser Wert in die lokale Zeitzone konvertiert.

Beim direkten Zugriff auf das REST-API muss daher darauf geachtet werden, den Inhalt von „Date“ in die jeweils lokale Zeitzone zu konvertieren.

Repräsentation als Array

Die Repräsentation dieses Suchergebnisses in einer Programmiersprache wie bspw. PHP oder Perl könnte bspw. so aussehen:

$VAR1 = { 
  'first' => 0, 
  'count' => 2, 
  'last' => 1, 
  'found' => 14, 
  'overall' => 25, 
  'licenseValid' => 1, 
  'limit' => 2, 
  'results' => [ 
                 {       
                   'Cc' => [], 
                   'Subject' => "Re: Anfrage bez\x{c3}\x{bc}glich Partnerschaft", 
                   'Date' => '201206191122', 
                   'Bcc' => [], 
                   'hasAttachment' => '1', 
                   'id' => '2012:748B034C4AF3004231D24B9DE2515822AB16485914AB3AE055C40DA336F4272F00', 
                   'To' => ['"W. Robert" <w.robert@robert-druck.de>'],      
                   'From' => 'info@hansen-und-meyer.de' 
                 },      
                 {       
                   'Cc' => [], 
                   'Subject' => "Re: Anfrage bez\x{c3}\x{bc}glich Partnerschaft", 
                   'Date' => '201206191122', 
                   'Bcc' => [], 
                   'hasAttachment' => '1', 
                   'id' => '2012:1C6626F5E02E1B3B0B74DE794BC67408A64484C8B8B98A83C130162B077AD6AB00', 
                   'To' => ['w.robert@robert-druck.de'],      
                   'From' => 'info@hansen-und-meyer.de' 
                 }       
               ]       
}

Abruf und Rückgabe einer E-Mail

Nachstehend ein Abruf einer E-Mail aus dem Archiv:

http://bennohost:21080/mail/?archive=BennoContainer&id=2012:1C6626F5E02E1B3B0B74D...A83C130162B077AD6AB00

Das Ergebnis (die E-Mail) wird standardmäßig in Form von JSON Objekten zurückgegeben und hat bspw. folgenden Inhalt:

{ 
          'body' => [ 
                      { 
                        'content-type' => 'text/plain', 
                        'data' => "Sehr geehrter Herr Robert, 

wir danken f\x{c3}\x{bc}r das Interesse an unseren Produkten, das Sie mit Ihrer 
E-Mail gezeigt haben. 

Wir haben dieser E-mail ein Angebot hinzugef\x{c3}\x{bc}gt und hoffen, dass wir 
baldig diesbez\x{c3}\x{bc}glich von Ihnen h\x{c3}\x{b6}ren werden. 
Unsere Gesch\x{c3}\x{a4}ftsbedingungen entnehmen Sie bitte den beigef\x{c3}\x{bc}gten 
PDF-Dokument. 

Bei weiteren Fragen stehen wir Ihnen selbstverst\x{c3}\x{a4}ndlich auch telefonisch 
zur Seite. Sie k\x{c3}\x{b6}nnen uns unter der Rufnummer 0541/123456-1, von Mo. bis 
Fr. zwischen 09:00 und 17:00 Uhr, erreichen. 

Mit freundlichen Gr\x{c3}\x{bc}\x{c3}\x{9f}en, 

Papierfabrik Hansen & Meyer GmbH 


i. A. 
Sabine Petersen 



Papierfabrik Hansen & Meyer GmbH | Seelenhof 5 | 49100 Sch\x{c3}\x{b6}nlingen | 
Tel.: 0541/123456-1 | info\@hansen-und-meyer.de 
" 
                      } 
                    ], 
          'attachments' => [ 
                             { 
                               'content-type' => 'application/pdf', 
                               'name' => 'preisangebot.pdf', 
                               'attachmentId' => "0",
                               'size' => 44513 
                             }, 
                             { 
                               'content-type' => 'application/pdf', 
                               'name' => 'agb.pdf', 
                               'attachmentId' => "1",
                               'size' => 63258 
                             } 
                           ], 
          'header' => { 
                        'Cc' => [], 
                        'User-Agent' => 'Mozilla-Thunderbird 2.0.0.22 (X11/20090706)', 
                        'Subject' => "Re: Anfrage bez\x{c3}\x{bc}glich Partnerschaft", 
                        'MIME-Version' => '1.0', 
                        'In-Reply-To' => '<4AC1E7D2.6070302@web.de>', 
                        'Date' => 'Tue, 19 Jun 2012 13:22:38 +0200', 
                        'Bcc' => [], 
                        'Size' => 109490, 
                        'References' => '<4AC1E7D2.6070302@web.de>', 
                        'Message-ID' => '<4AC1EDFE.8070406@web.de>', 
                        'Content-Type' => 'multipart/mixed; boundary="------------070101070508030007040901"', 
                        'To' => [ 
                                  'w.robert@robert-druck.de' 
                                ], 
                        'From' => 'info@hansen-und-meyer.de'
                        'X-Benno-HashCheckPassed' => true,
                        'X-Benno-DateTS' => 1340104958
                      },
        };

HTTP Fehlercodes

  • 400 - Fehler beim Request
  • 404 - Container nicht gefunden
  • 503 - Interner Fehler
  • 901 - Index nicht initialisiert
rest_api.txt · Zuletzt geändert: 2023/11/02 09:56 von lwsystems