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"
}
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."
}
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);
InputStream body = request.getInputStream();
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!');
?>
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,
));
}
}
?>
<?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);
}
?>
