Deutsch

SMS Programmierschnittstelle (SMS API)

Endpunkte

Die ersten Fragen die sich bei der Implementierung stellen sind wohin und wie die API-Aufrufe gesendet werden sollen. My-Cool-SMS unterstützt GET, POST und JSON Aufrufe auf Port 80 oder Port 443 mittels SSL. Es können hierbei die jeweils folgenden URLs verwendet werden.

HTTP

Der API-Endpunkt für HTTP-Aufrufe ist:
http://www.my-cool-sms.com/api-socket.php

HTTPS

Falls eine verschlüsselte Verbindung erforderlich ist kann die API auch mittels SSL auf Port 443 verwendet werden.
Der API-Endpunkt für HTTPS-Aufrufe ist:
https://www.my-cool-sms.com/api-socket.php

API Komponenten

My-Cool-SMS hat zwei Arten von API Komponenten. Funktionen und Rückrufe.

Funktionen

Funktionen werden benutzt um beispielsweise eine SMS Text Nachricht zu versenden, das Rest-Guthaben abzufragen oder Sendeberichte abzurufen. Eine Funktion kann über die weiter unten beschriebene HTTP-Struktur aufgerufen werden.

Rückrufe

Rückrufe werden von My-Cool-SMS automatisch und in Echtzeit an einen voreingestellten Web-Server gesendet sobald ein bestimmes Ereignis eintritt. Solch ein Ereignis kann beispielsweise der Eingang einer SMS oder eines Sendeberichts sein.

Aufruf-Struktur

Die API kann mittels POST, GET oder JSON aufgerufen werden. Obwohl My-Cool-SMS niemanden davon abhält POST oder GET zu benutzen ist es empfohlen JSON Aufrufe zu verwenden. JSON ist ein schlankes Datenaustausch-Format dass für Menschen leicht lesbar und für Maschinen leicht zu erstellen und zu parsen ist. Es wird von den allermeisten Programmier und Skriptingsprachen unterstützt und im Vergleich zu GET oder POST zuverlässiger und leichter zu bedienen wenn beispielsweise Unicode Nachrichten versendet werden sollen.
Mittels JSON müssen Unicode JSON-Nachrichten nicht in ein spezielles Format (UCS2) umgewandelt werden, da My-Cool-SMS die Kodierung automatisch ermittel kann. Falls du schonmal mit einer SMS API gearbeitet hast wirst du vermutlich erleichtert sein dass bei My-Cool-SMS keine speziellen Kodierungen erforderlich sind. Wer mehr über JSON erfahren möchte kann das hier tun.

Anmeldeinformationen und Funktions-Selektoren

Jeder Aufruf der My-Cool-SMS muss mindestens drei Parameter enthalten. Zum müssen der Benutzername (username) und das Passwort (password) und zum anderen ein Funktions-Selektor (function) angegeben werden, der der API sagt was getan werden soll.

JSON

Lass uns einen Blick auf ein Beispiel werfen das benutzt werden kann um den Wert des verbleibenden Rest-Guthabens abzurufen:
{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

POST/GET

Mit POST oder GET schaut der gleiche Aufruf wie folgt aus:
username=xxx&password=yyyy&function=getBalance

Erforderiche und Optionale Parameter

Während der Benutzername, das Passwort und der Funktions-Selektor immer erforderlich sind kann jede Funktion eine unterschiedliche Anzahl and erforderlichen oder optionalen Parametern erfordern.
Wenn beispielsweise ein Sendebericht abgerufen werden soll, muss man mitangeben für welche SMS der Sendebericht gewünscht wird. Dies geschieht durch die einfache Angabe eines weiteren Parameters, in diesem Fall "id".
{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Antwort-Struktur

Ein API Aufruf gibt immer ein JSON-Objekt zurück. Jede Antwort enthält grundsätzlich einen success Parameter der anzeigt ob der Aufruf erfolgreich war oder ein Fehler gemeldet wird. Je nachdem ob success auf true oder false gesetzt ist sollte die Antwort unterschiedlich verarbeitet werden.

Bestätigungs-Antwort

Ein erfolgreicher Aufruf der getDeliveryReport-Funktion würde beispielsweise ein JSON-Objekt ähnlich dem folgenden enthalten:
{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}
Jede Funktion hat verschiedene Antwort-Parameter. Eine detaillierte Spezifikation kann hier eingesehen werden.

Fehler-Antwort

Angenommen es ist ein Rechtschreibfehler im gesendeten Passwort-Parameter. In diesem Fall würde das zurückgegeben JSON-Objekt folgendermaßsen aussehen.
{
    "success":false,
    "errorcode":"101",
    "description":"Login Failed. Wrong Username or Password."
}
Falls der success Parameter false ist können immer ein Fehler-Code (errorcode) bestehend aus drei Zeichen, sowie eine Beschreibung (errordescription) in der Antwort erwartet werden.

Verarbeiten von Antworten

Antwort Auslesen

Die API Antwort wird immer als JSON-String zurückgegeben. Das ist gut, denn die meisten Programmiersprachen können einen solchen String per simplen Funktionsaufruf in ein Objekt oder Array umwandeln. Alles was also getan werden muss ist die Antwort an die Dekodierungs-Funktion der verwendeten Programmiersprache zu übergeben und den Rückgabe-Wert bequem auszulesen.
Um mehr Informationen über JSON für die Programmiersprache deiner Wahl herauszufinden folge diesem Link und scrolle ein wenig nach unten.
In PHP könnte man eine API Antwort wie folgt verarbeiten:
// Let's assume you sent a getDeliveryReport request and
// the HTTP response is stored in $response...

// Now simply convert the response into a PHP object
$oResponse = json_decode($response);

//$oResponse is now an object

if($oResponse->success) {
    //Great. It worked!
    echo($oResponse->smsid);
    echo($oResponse->status);
} else {
    //Oops. something went wrong.
    echo($oResponse->errorcode);
    echo($oResponse->description);
}

Verarbeiten von Rückrufen

Eingabe Auslesen

Rückrufe unterscheiden sich in ihrer Struktur kaum von einer API-Antwort. Es handelt sich ebenfalls um ein JSON Objekt das übergeben wird und genauso verarbeitet werden kann wie eine API-Antwort. Das JSON Objekt wird als HTTP Raw Data übergeben und kann wie folgt ausgelesen werden.
In PHP könnte man einen API Rückruf wie folgt verarbeiten:
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));

//$oCallback is now an object.
print_r($oCallback);
In Java ist es ungefähr genauso:
InputStream body = request.getInputStream();
Bitte beachte dass die HTTP Raw Data nur ein einziges mal ausgelesen werden kann und zur weiteren Verarbeitung in einer Variable gespeichert werden sollte.

PHP Beispiele

Funktion: sendSms

Lass uns einen Blick auf ein bisschen Programmiercode werden der verwendet werden könnte um eine SMS zu verschicken. Du möchtest vermutlich so wenig Code wie möglich verwenden. Würden dir folgende Zeilen gefallen?
<?php

$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

?>
Nicht schlecht? Falls dies alles ist was du brauchst kannst du das PHP Anfänger Kit herunterladen, einen Blick auf die Kommentare im Code werfen und schon geht es los!

PHP SMS Anfänger Kit

PHP Anfänger Kit herunterladen
Im Anfänger Kit enthalten ist fertiger Code zum aufrufen von API Funktionen sowie zum verarbeiten von API Rückrufen.

Für Techies

Falls Interesse besteht kannst du auch einen Blick auf die PHP Klasse werfen die den API Aufruf erstellt und sendet:
<?php

class MyCoolSMS {

    function __construct() {
    
        $this->username = 'xxx'; //your username here...
        $this->password = 'yyy'; //your password here...
        $this->endpoint = 'http://www.my-cool-sms.com/api-socket.php';
    }

    public function sendSms($number, $message, $senderid='MyNumber') {
    	
        return($this->request(json_encode(array(
            'username' => $this->username,
            'password' => $this->password,
            'function' => 'sendSms',
            'number' => $number,
            'senderid' => $senderid,
            'message' => $message
        ))));
        
    }
    
    public function getDeliveryReport() {}
    
    public function getBalance() {}
    
    //add more functions as you please...
    
    private function request($oRequest) {
    
        $oCurl = curl_init($this->endpoint);
        curl_setopt($oCurl, CURLOPT_POST, 1);
        curl_setopt($oCurl, CURLOPT_POSTFIELDS, $oRequest);
        curl_setopt($oCurl, CURLOPT_RETURNTRANSFER, 1);
        
        if(curl_errno($oCurl) == 0) {
            $oResponse = json_decode(curl_exec($oCurl));
            if(!is_object($oResponse)) {
                $oResponse = $this->getError('001', 'Bad Response');
            }
        } else {
            $oResponse = $this->getError(curl_error($oCurl));
        }		
    
        curl_close($oCurl);
        
        return $oResponse;
    
    }
	
    private function getError($error = '000', $description = NULL) {

        return json_encode(array(
            'success' => false,
            'error' => $error,
            'description' => $description,
        ));
        
    }

}

?>
Speicher obenstehenden Code in eine Datei namens MyCoolSMS.class.php und dann kann es folgendermaßen losgehen:
<?php

require_once('MyCoolSMS.class.php');

$oMyCoolSMS = new MyCoolSMS();
$oResponse = $oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

if($oResponse->success) {
    //Great, it worked!
    print_r($oResponse);
} else {
    //Oops, Something went wrong...
    print_r($oResponse);
}

?>

Es kann losgehen!

Lass uns jetzt einen Blick auf die API Funktions- und Rückruf-Dokumentation werden.
Haben wir etwas vergessen? Gibt es Fragen? Vorschläge oder Ideen was noch hinzugefügt werden sollt? Fall ja, lass es uns bitte wissen!
© My-Cool-Webservices Ltd. 2008-2014
English
Español
Français
Nederlands
Polski
Português
Руccкий
繁体中文