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

• Die API kann nur mit PHP 5 oder neuer verwendet werden, PHP 4 wird nicht unterstützt.
• Nur UTF-8 codierte Daten dürfen verwendet werden, eine Umwandlung von nicht UTF-8 codierten Daten führt zu Fehlern bzw. zu leeren Rückgabewerten.

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.

Header Access-Control-Allow-Origin für die Aufrufe
Für Cross-Domain-Aufrufe wird der Header-Eintrag Access-Control-Allow-Origin mit dem Wildcard-Zeichen * verwendet. In der Datei userdefined.inc.php kann bei der Konstante JS_Access_Control_Allow_Origin ein http://-Aufruf angegeben werden, welcher nur den Zugriff über die jeweilige Domain erlaubt.

Siehe dazu auch
Cross-Origin Resource Sharing

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:

Definierte Klassen

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