Základní pojmy

Kanálem, přes který probíhá veškerá komunikace, je HTTPS. HTTP je jednoduchý textový protokol, S na konci znamená Secure = komunikace s API je možná pouze v šifrované formě (žádné citlivé informace nemůže potenciální útočník odposlechnout po cestě).
API je bezstavové, pracuje na principu request-response = každý požadavek na API je nezávislý na předchozích/následujících požadavcích.
Každý zdroj dat (tzv. resource) reprezentuje určitá URL. Na zdrojem lze provádět různé akce pomocí HTTP metod. Metoda GET získá ze zdroje data. POST vytváří nový zdroj. PUT mění resource na dané URL. DELETE smaže daný resource. URL zdrojů budou uváděny většinou bez API rootu.
Data jsou přenášena ve formátu JSON, všechny odpovědi mají nastavenu hlavičku Content-Type: application/json. Stejně tak se očekává od vstupních dat v požadavcích.

Zabezpečení

Jak bylo napsáno výše, komunikace probíhá šifrovaně pomocí HTTPS; případný útočník tedy nemůže odposlechnout potenciálně citlivá data, která si skrz API s Můj.Skrz.cz vyměňujete.

Autentizace se řeší pomocí HTTP basic auth a hlavičky Authorization. Uživatelské jméno (= email) a heslo pro API je stejné jako pro přihlášení na Můj.Skrz.cz.

Pokud budu mít uživatelské jméno franta@skrz.cz a heslo sedmikraska, spojím řetězce dohromady pomocí dvojtečky : a zakóduju v Base64, vznikne tzv. basic cookie, pro tento příklad je to např. ZnJhbnRhQHNrcnouY3o6c2VkbWlrcmFza2E=. Tu vložím do s označením, že jde o Basic auth, do hlavičky Authorization:

Authorization: Basic ZnJhbnRhQHNrcnouY3o6c2VkbWlrcmFza2E=

Přímo toto za vás většinou vyřeší knihovna (např. v PHP curl, viz níže), kterou používáte - té nastavujete pouze, že chcete použít HTTP basic auth a uživatelské jméno a heslo.

API root

URL budou uváděny relativně vůči tzv. API rootu, ten je:

https://muj.skrz.cz/api/v2

Pokud mám tedy např. resource /campaigns, jeho absolutní URL je https://muj.skrz.cz/api/v2/campaigns.

Příklady

Curl

Nejsnažším způsobem, jak testovat API Můj.Skrz.cz, je použít CLI nástroj curl, např. výpis zdroje /campaigns:

$ curl -u franta@skrz.cz:sedmikraska -X GET https://muj.skrz.cz/api/v2/campaigns?pretty
{
    "data": [
        {
            "id": 9999,
            "title": "Frantova cestovka",
            "slug": "FRAD000001",
            "publisher": {
                "id": 1,
                "title": "Skrz.cz"
            },
            "uri": "/api/v2/campaigns/9999"
        }
    ]
}

Všimněte si triku s použitím query parametru ?pretty.

Bez něho se JSON v odpovědi vrací bez bílých znaků = aby byl co nejúspornější, tak ho chcete používat při produkčním nasazení. Ovšem při testování je hloupé dostat jednu dlouhou neformátovanou špagetu znaků. Query parametr ?pretty zapříčiní, že se JSON vrátí hezky odsázený.

PHP

Obdobně lze poslat požadavek v PHP:

<?php
$username = "franta@skrz.cz";
$password = "sedmikraska";

$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_URL, "https://muj.skrz.cz/api/v2/campaigns");
curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password);
$response = curl_exec($ch);
if ($response === false) {
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    throw new \RuntimeException("Request failed.", $statusCode);
} else {
    $response = json_decode($response);
    // work with $response
}

Příklad požadavku, který má i tělo, např. změna CPC:

<?php
$username = "franta@skrz.cz";
$password = "sedmikraska";
$payload = array(
    "clickCommission" => 1.6,
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_URL, "https://muj.skrz.cz/api/v2/campaigns/9999/promo/12345");
curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
$response = curl_exec($ch);
if ($response === false) {
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    throw new \RuntimeException("Request failed.", $statusCode);
} else {
    $response = json_decode($response);
    // work with $response
}

Kolekce

Jestliže výstupem resource v API je kolekce prvků, taková kolekce je vždy obalena JSON objektem a je pod klíčem data, viz např. GET /campaigns/{campaign}:

$ curl -u franta@skrz.cz:sedmikraska -X GET https://muj.skrz.cz/api/v2/campaigns?pretty
{
    "data": [
        {
            "id": 9999,
            "title": "Frantova cestovka",
            "slug": "FRAD000001",
            "publisher": {
                "id": 1,
                "title": "Skrz.cz"
            },
            "uri": "/api/v2/campaigns/9999"
        }
    ]
}

Stránkování

Pokud je kolekce příliš velká na to, aby se vešla do odpovědi, je stránkovaná. Stránkovaná odpověď má krom klíče data ještě přítomen klíč pagination, např. GET /campaigns/{campaign}/promo:

$ curl -u franta@skrz.cz:sedmikraska -X GET https://muj.skrz.cz/api/v2/campaigns/9999/promo?pretty
{
    "data": [
        {
            "id": 123456,
            "title": "Frantovy týdenní prodeje",
            "remoteItemId": "1",
            "dealId": 123456,
            "leafletId": null,
            "clickCommission": 10.5,
            "conversionPercent": 0.030,
            "published": true,
            "uri": "/api/v2/campaigns/144/promo/661294"
        },
        ...
    ],
    "pagination": {
        "next": "/api/v2/campaigns/FRAD000001/promo?pretty&limit=100&offset=100"
    }
}

Stránkování se řídí query parametry limit a offset. Jejich název je snad všeříkající.

limit - nastaví maximální počet prvků v odpovědi. Maximálně lze u stránkovaných odpovědí vybrat 100 položek najednou.
offset - kolik položek od začátku vynechat, než se vezme limit položek.

REST API v2