API (JSON) zur Manipulation der Daten verwenden

Die auf JavaScript Object Notation (JSON) basierte API kann genutzt werden, um Daten zwischen verschiedenen Anwendungen auszutauschen. Es sollte, die auf JSON basierte API, nur verwendet werden, wenn der Aufruf der API per SOAP nicht möglich ist. Die auf JSON basierte API wird intern auf die SOAP API umgeleitet, entsprechend wird mehr Serverzeit für die Umwandlung der Aufrufe benötigt.

Siehe dazu auch
API (SOAP Webservice) zur Manipulation der Daten verwenden

 

Voraussetzung für den Einsatz der API

 

Aufruf der API mit JSON
Die API rufen Sie über http://<ihre _domain>/<installations_verzeichnis>/api/api_json.php im eigenen Script auf. Im Browser kann dieses Script nicht direkt aufgerufen werden, es wird eine Fehlermeldung zurückgegeben, denn alle Parameter müssen per HTTP POST übergeben werden.

 

Authentifizierung
Für die Authentifizierung wird ein API Key benötigt, diesen finden Sie unter Menü Benutzer - Eigenes Konto ändern.
Hinweis: Nur die Nutzertypen SuperAdmin und Admin verfügen über einen API Key, normale Nutzer dürfen nicht per API zugreifen.

Die Authentifizierung erfolgt über einen Header-Eintrag beim HTTP-Aufruf des Scripts api_json.php, der Name des Header lautet APIToken. Nur durch korrekte Übergabe des API Key bei jedem Aufruf wird ein Zugriff auf die gespeicherten Daten erlaubt.

Der API Key selbst erlaubt nur den Zugriff auf die Daten des SuperAdmin oder Admins selbst, nicht auf andere Admin-Nutzer.

 

Zeichen-Codierung der Daten
Alle Daten werden UTF-8 codiert zurückgegeben bzw. müssen mit der Codierung UTF-8 übergeben werden, ansonsten kann es zur unvollständigen Übertragung der Daten kommen bzw. die Aufrufe scheitern komplett.

 

Name und Parameter der Funktionen

Rufen Sie die SOAP API über http://<ihre _domain>/<installations_verzeichnis>/api/api.php direkt im Browser auf, es werden dabei alle Funktionen, Parameter und die Beschreibung der Funktionen dargestellt. Für den JSON-Aufruf ersetzen Sie den Punkt zwischen Klassenname und Funktionsname durch 2 Unterstriche __. z.B. api_Common.api_testAPI ändern in api_Common__api_testAPI.

Die Parameter müssen beim JSON-Aufruf in gleiche Reihenfolge und Schreibung übergeben werden, wie diese angezeigt werden. z.B.

api_Recipients.api_createRecipient

=> ändern in api_Recipients__api_createRecipient

angezeigte Input Parameter

    apiMailingListId: xsd:int
    apiData: xsd:Array
    apiarrayGroupsIds: xsd:Array
    apiUseDoubleOptIn: xsd:boolean

=> Übergabe als

array("apiMailingListId" => <id der Liste>, "apiData" => array(), "apiarrayGroupsIds" => array(), "apiUseDoubleOptIn" => false)

 

Datentypen
Folgende Datentypen werden verwendet:

XML Schema Datentyp Datentyp in PHP und anderen Programmiersprachen
xsd:string string
xsd:int integer
xsd:float float
xsd:boolean boolean
xsd:double double
xsd:Array array
xsd:datetime datetime

 

Definierte Klassen

Klassenname Beschreibung
api_Common Enthält grundlegende Funktionen, die teilweise nur als Nutzer SuperAdmin aufgerufen werden können.
api_Mailinglists Enthält Funktionen zur Manipulation von Empfängerlisten.
api_Recipients Funktionen zur Manipulation der Empfänger in den Empfängerlisten.
api_Users Enthält Funktionen zum Anlegen und Entfernen von Nutzern.
api_DistributionLists Enthält Funktionen für die Verteilerlisten.

 

Nur nutzbar mit SuperMailingList Professional, SuperWebMailer Professional und SuperWebMailer Enterprise.

 

Nur SuperWebMailer
api_Campaigns Enthält Funktionen für das Erstellen, Ändern und Abrufen von Statistiken für E-Mailings.

 

api_FUResponders Enthält Funktionen für das Erstellen, Ändern und Abrufen von Statistiken für Folow-Up-Auto-Responder.

Nicht in SuperWebMailer Basic nutzbar.

 

 

Beispiel für eine JSON-Aufruf zur Bestimmung der API Version in PHP

Im api-Verzeichnis finden Sie die Datei json_sample.php diese zeigt den Aufruf verschiedener Funktionen.

Einfaches Beispiel in PHP zur Bestimmung der API Version

<?php

   # show all errors in browser
   error_reporting( E_ALL & ~ ( E_DEPRECATED | E_STRICT ) );
   ini_set("display_errors", 1);

   $APIToken = "123456789";
   $host = "localhost";
   $path_api_json_php = "/newsletter/api/api_json.php";
   $port = 80; // 443 for https


   // XML SOAP request: api_Common.api_getAPIVersion => api_Common__api_getAPIVersion
   $data = array("api_Common__api_getAPIVersion" => json_encode(array()));


   $ret = sampleDoHTTPPOSTRequest($host, $path_api_json_php, $data, $port, array("APIToken" => $APIToken));

   if( $ret !== false){
     if(isValidJson($ret)) {
       $j = json_decode($ret, true);
       if(!is_array($j))
         print $j;
         else {
           if(isset($j["error_code"])) { // is an error?
             print "An error:\r\n";
             print_r($j);
           }
           else
            print_r($j); // no error
         }
       }
       else
         print_r($ret);
   } else {
     print "Request failed / Aufruf gescheitert!";
   }

   /* other helper functions see json_sample.php */

?>
  

Beispiel für JSON-Aufruf zur Bestimmung API Version mit JavaScript und JQuery

Im api-Verzeichnis finden Sie die Datei json_javascript_sample.html diese zeigt den Aufruf verschiedener Funktionen.

<html>
<head>
<title></title>
<meta name="generator" content="Edit4Win">

<script src="http://code.jquery.com/jquery-1.12.0.min.js"></script>

<script language="JavaScript">
<!--
   var APIToken = "123456789";
   var host = "http://localhost";
   var path_api_json_php = "/newsletter/api/api_json.php";


   function TestRequest(){

      var data = {api_Common__api_getAPIVersion: JSON.stringify( {} ) };

      // SAMPLE 2 var data = {api_Common__api_getRecipientsFieldnames: JSON.stringify( {apiLanguageCode: "de"} ) };

      // JQuery decoded values itself when content-type is application/json
      $.ajax({
        url: host + path_api_json_php,
        cache: false,
        type: "post",
        headers: {"APIToken": APIToken},
        data: data,
        success: function(data) {
          if(data.error == null) { // check for errors
              if(typeof data !== "object")
                alert("Success return value: " + data)
                else{
                 // for SAMPLE 2 api_Common__api_getRecipientsFieldnames
                 var s = "";
                 for (var key in data) {
                   s = s + "\r\n" + data[key].fieldname;
                 }
                 alert("Success return value: " + s);
                }
            }
            else
            alert("Failed:" + data.error + " " + data.error_code)
        },
        error: function(data) {
          alert("Failed: " + data.status + " " + data.statusText);
        }
      });

   }


//-->
</script>


</head>
<body>

<input type="button" name="test" value="Test" onclick="TestRequest()">

</body>
</html>

  

 

 

Siehe dazu auch
API (SOAP Webservice) zur Manipulation der Daten verwenden