API-kutsun tekeminen

Tunnusten luominen

API:n kanssa käytettäviä tunnuksia voidaan lisätä Creamailerin ylläpidosta oman käyttäjätunnuksen alta kohdasta Asetukset ja valitsemalla API. Uudelle tunnukselle voidaan antaa luku tai luku/kirjoitus -oikeudet.

Tunnistautuminen

Creamailerista löytyvää Asiakastunnusta {ACCESS_TOKEN} käytetään asiakkaan tunnistamiseen. Lisäksi jokaista kutsua varten on laskettava tarkistesumma käyttäen Creamailerista löytyvää asiakastunnukseen liittyvää yhteistä tunnistetta, aikaleimaa, kutsun www-osoitetta ja JSON-bodyä. Näistä muodostetaan hash käyttäen sha1-salausta. Creamailerista löytyvää yhteistä tunnistetta ei lähetetä koskaan API-kutsun mukana.

Tarkistesumman muodostaminen (PHP):

$request_signature = sha1("https://api.cmfile.net/v1/api/lists.json" . '{"name":"Listan nimi","language":"fi","auto_suppress":true}' . "1379081867" . "{SHARED_SECRET}");

Aikaleiman muodostamiseen voidaan käyttää esim. PHP:n time() -funktiota.

Katso tarkemmat ohjeet ja esimerkit eri ohjemointikielille.

Formaatti

Creamaileriin voi lähettää tietoja pelkästään JSON-formaatissa UTF-8, joka on määriteltävä myös jokaisen API-kutsun Headeriin Content-Type: application/json. Kutsun yhteydessä määritellään missä muodossa tiedot halutaan takaisin Creamailerista joko käyttäen Headerin Accept-parametriä {application/json|application/php|application/xml} tai vaihtoehtoisesti tämä voidaan määritellä suoraan www-osoitteessa lisäämällä urlin perään piste ja haluamasi formaatti esim. /v1/api/lists.{xml|json|php}.

• JSON Tiedot palautetaan JSON-formaatissa ja voidaan dekoodata käyttäen esimerkiksi PHP:n json_decode()-functiota.
• XML Tiedot palautetaan XML-muodossa ja käsitellään haluamalla tavalla.
• PHP Tiedot palautetaan PHP:n Serialized-formaatissa. Tiedot voidaan dekoodata esimerkiksi käyttäen PHP:n unserialize()-funktiota.

API-kutsun tekeminen

API:n käyttäminen onnistuu ainoastaan salatun HTTPS-yhteyden kautta. Alla esimerkki uuden listan luomisesta PHP:n ja cURL:in avulla. ACCESS_TOKEN ja SHARED_SECRET korvataan ylläpidosta löytyvillä tunnuksilla.

Autentikointi tapahtuu aina kutsun headerissa, josta tulee löytyä X-Access-Token, X-Request-Signature ja X-Request-Timestamp.

PHP esimerkki

define("ACCESSTOKEN", "{ACCESS_TOKEN}");
define("SHAREDSECRET", "{SHARED_SECRET}");
define("CMURL", "https://api.cmfile.net/v1/api");
 
$query = array(
    "name" => "Esimerkkilista",
    "language"  => "fi",
    "auto_suppress"  => TRUE
);
 
// API call
$data = curl_wrap('/lists', 'POST', json_encode($query));
 
// Show result data
var_dump($data);
 
function curl_wrap($url, $action, $json = NULL, $timestamp = NULL, $format = 'application/json')
{
    // Timestamp
    if (! $timestamp) $timestamp = time();
 
    // Build hash from all the data for security (url, json string, timestamp and shared secret)
    $hash = sha1(CMURL . $url . $json . $timestamp . SHAREDSECRET);
 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_HEADER, FALSE);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($ch, CURLOPT_MAXREDIRS, 10 );
    curl_setopt($ch, CURLOPT_URL, CMURL.$url);
 
    switch($action){
        case "POST":
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
            curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
            break;
        case "GET":
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
            break;
        case "PUT":
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
            curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
            break;
        case "DELETE":
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
            break;
        default:
            break;
    }
 
    curl_setopt($ch, CURLOPT_HTTPHEADER, 
        array('X-Access-Token:' . ACCESSTOKEN,
              'X-Request-Signature:' . $hash,
              'X-Request-Timestamp:' . $timestamp,
              'Accept:' . $format,
              'Content-Type: application/json; charset=UTF-8'
    ));
 
    curl_setopt($ch, CURLOPT_USERAGENT, "Creamailer-PHP/1.0'");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    $output = curl_exec($ch);
    curl_close($ch);
    return $output;
}

cURL esimerkki

curl -i https://api.cmfile.net/v1/api/lists.json -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIQNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -H "Accept: application/json; version=v1" -H "Content-Type: application/json" -d '{"listName":"Listan nimi","listLanguage":"fi","listAutoSuppress":true}' -X POST