From 60b17b3058bee155d03921bb0dfdabee274e9719 Mon Sep 17 00:00:00 2001 From: Moritz Bunkus Date: Fri, 22 Mar 2019 12:55:41 +0100 Subject: [PATCH] =?utf8?q?Dokumentation:=20zu=20programmatischen=20API-Auf?= =?utf8?q?rufen=20erg=C3=A4nzt?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit --- doc/dokumentation.xml | 83 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/doc/dokumentation.xml b/doc/dokumentation.xml index 98eadf1b9..b9b7e11f8 100644 --- a/doc/dokumentation.xml +++ b/doc/dokumentation.xml @@ -7825,6 +7825,89 @@ file_name = /tmp/kivitendo-debug.log + + Programmatische API-Aufrufe + + + Einführung + + + Es ist möglich, Funktionen in kivitendo programmatisch aus anderen Programmen aufzurufen. Dazu ist nötig, dass + Authentifizierungsinformationen in jedem Aufruf mitgegeben werden. Dafür gibt es zwei Methoden: die HTTP-»Basic«-Authentifizierung + oder die Übergabe als spziell benannte GET-Parameter. Neben den Authentifizierungsinformationen muss auch der zu verwendende Mandant + übergeben werden. + + + + + Wahl des Mandanten + + + Der zu verwendende Mandant kann als Parameter {AUTH}client_id mit jedem Request mitgeschickt werden. Der Wert + muss dabei die Datenbank-ID des Mandanten sein. kivitendo prüft, ob der Account, der über die Authentifizierungsinformationen + übergeben wurde, Zugriff auf den angegebenen Mandanten hat. + + + + Wird in einem Request kein Mandant mitgegeben, so wird derjenige Mandant genommen, wer als Standardmandant markiert wurde. Gibt es + keinen solchen, kommt es zu einer Fehlermeldung. + + + + + HTTP-»Basic«-Authentifizierung + + + Für diese Methode muss jedem Request der bekannte HTTP-Header Authorization mitgeschickt werden (siehe RFC 7617). Unterstützt wird ausschließlich die »Basic«-Methode. Loginname und + Passwort werden bei dieser Methode durch einen Doppelpunkt getrennt und Base64-encodiert im genannten HTTP-Header übertragen. + + + + Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei Benutzung über den Webbrowser, ob + dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat. + + + + Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschließlich über HTTPS verschlüsselt + erfolgen. + + + + + Authentifizierung mit Parametern + + + Für diese Methode müssen jedem Request zwei Parameter mitgegeben werden: {AUTH}login und + {AUTH}password. Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei + Benutzung über den Webbrowser, ob dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat. + + + + Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschließlich über HTTPS verschlüsselt + erfolgen. + + + + + Die Verwendung dieser Methode ist veraltet. Statt dessen sollte die oben erwähnte HTTP-»Basic«-Authentifizierung verwendet werden. + + + + + + Beispiele + + + Das folgende Beispiel nutzt das Kommandozeilenprogramm »curl« und ruft die Funktion auf, die eine vorhandene Telefonnummer in den + Ansprechpersonen sucht und dazu Informationen zurückliefert. Dabei wird die HTTP-»Basic«-Authentifizierung genutzt. + + + $ curl --silent --user 'jdoe:SecretPassword!' \ + 'https://…/controller.pl?action=PhoneNumber/look_up&number=053147110815' + + + SQL-Upgradedateien -- 2.20.1