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 lasketaan HMAC-SHA256-tarkistesumma käyttäen Creamailerista löytyvää asiakastunnukseen liittyvää yhteistä tunnistetta, aikaleimaa, kutsun täyttä URL-polkua (query string mukaan luettuna), sekä JSON-bodyä.

Creamailerista löytyvää yhteistä tunnistetta ei lähetetä koskaan API-kutsun mukana, sitä käytetään vain HMAC:in avaimena.

Tarkistesumman muodostaminen (PHP)

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

Komponentit yhdistetään merkkijonoksi tässä järjestyksessä: base_url + "/" + path + query_string + body + timestamp.

query_string alkaa kysymysmerkillä jos kyselyä on (esim. ?email=user@example.com), muutoin se on tyhjä merkkijono.

Aikaleima tulee olla ±5 minuutin sisällä palvelimen kellosta — muutoin kutsu hylätään.

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

Katso tarkemmat ohjeet ja esimerkit eri ohjelmointikielille.

Formaatti

Creamailer API v2 käyttää ainoastaan JSON-formaattia (UTF-8).

Lähetä kaikissa POST- ja PUT-kutsuissa header Content-Type: application/json.

Vastaus palautetaan aina JSON-muodossa. Vanhempia application/xml- ja application/php-formaatteja ei enää tueta v2:ssa, eikä URL-suffikseja (.json, .xml, .php) käytetä.

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
• X-Request-Timestamp

PHP-esimerkki

define("ACCESSTOKEN", "{ACCESS_TOKEN}");
define("SHAREDSECRET", "{SHARED_SECRET}");
define("BASEURL", "https://api.cmfile.net");

$body = [
    "name"          = "Esimerkkilista",
    "language"      = "fi",
    "auto_suppress" = true,
];

// API call: POST /v2/api/lists
$data = curl_wrap('v2/api/lists', 'POST', $body);

// Show result data
var_dump($data);

function curl_wrap($path, $method, $body = null, array $query = [])
{
    $timestamp   = (string) time();
    $bodyString  = $body !== null ? json_encode($body) : '';
    $queryString = ! empty($query) ? '?' . http_build_query($query) : '';

    // Build HMAC-SHA256 signature
    $data      = BASEURL . '/' . $path . $queryString . $bodyString . $timestamp;
    $signature = hash_hmac('sha256', $data, SHAREDSECRET);

    $url = BASEURL . '/' . $path . $queryString;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    curl_setopt($ch, CURLOPT_USERAGENT, 'Creamailer-PHP/2.0');

    // TLS verification stays ON — required by the v2 API
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);

    if ($bodyString !== '') {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $bodyString);
    }

    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: '      . ACCESSTOKEN,
        'X-Request-Signature: ' . $signature,
        'X-Request-Timestamp: ' . $timestamp,
        'Content-Type: application/json',
        'Accept: application/json',
    ]);

    $output   = curl_exec($ch);
    $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($output === false) {
        $err = curl_error($ch);
        curl_close($ch);
        throw new RuntimeException('cURL error: ' . $err);
    }

    curl_close($ch);

    return [
        'status' = $httpCode,
        'body'   = json_decode($output, true),
    ];
}

Huomaa, että v2:ssa polku annetaan ilman alkavaa kauttaviivaa (v2/api/lists), ja signatuuriin lisätään / erikseen base-URLin ja polun väliin.

Sama logiikka pätee query stringiin: jos sitä on, se sisältyy allekirjoitukseen ?-merkkiä myöten.

cURL-esimerkki

TOKEN="{ACCESS_TOKEN}"
SECRET="{SHARED_SECRET}"
BASE_URL="https://api.cmfile.net"
PATH="v2/api/lists"
TIMESTAMP=$(date +%s)
BODY='{"name":"Listan nimi","language":"fi","auto_suppress":true}'

DATA="${BASE_URL}/${PATH}${BODY}${TIMESTAMP}"
SIGNATURE=$(echo -n "$DATA" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -i "${BASE_URL}/${PATH}" \
  -H "X-Access-Token: ${TOKEN}" \
  -H "X-Request-Signature: ${SIGNATURE}" \
  -H "X-Request-Timestamp: ${TIMESTAMP}" \
  -H "Content-Type: application/json" \
  -d "$BODY" \
  -X POST

Jos käytät PHP:ta, suosittelemme kuitenkin valmista SDK-kirjastoa, joka hoitaa allekirjoituksen, virheenkäsittelyn ja sivutuksen puolestasi, silloin ei tarvitse kirjoittaa cURL-wrapperia itse.