Použití Postman pro práci s API

Postman je populární nástroj pro testování API, který:

poskytuje řadu užitečných nástrojů
je multiplatformní (pro mac, linux, windows)
lze používat bezplatně
lze jej využít i pro testování naší REST API na backendu

Link ke stažení: https://www.postman.com

Nastavení

Ať už začínáte, nebo postman používáte delší dobu, určitě se pro tento projekt hodí založit nový vlastní workspace.

Návod zde: https://learning.postman.com/docs/postman/workspaces/creating-workspaces/

Pro nás účel postačí použít lokální - blank workspace.

Import

Možnosti API se během vývoje neustále mění a hlavně rozšiřují o nové endpointy. Proto je vhodné začít importem aktuální verze.

Export specifikace API je možné získat z adresy https://app.mailship.eu/api/doc.json (případně https://app.mailship.eu/api/doc ). Pokud se vám místo stažení zobrazí v prohlížeči, uložte jej.

Pro import použijte tlačítko Import v levém horním rohu. Poté se otevře okno, které umožní nahrát soubor (stačí přetáhnout) nebo vložit text ze schránky (v případě, že jsme si zkopírovali JSON z adresy https://app.mailship.eu/api/doc.json stačí vložit do řádku “Paste cURL, Raw text or URL…”

V dalším kroku se dostanete na detaily k importu. Automaticky bude předvoleno Postman Collection. Pak stačí kliknout na tlačítko Import. Po potvrzení kliknutím na tlačítko Import dojde k dokončení importu a založení nové kolekce.

Autorizace

Krom několika vybraných endpointů (např. /login) je vyžadováno ověření v podobě tokenu. To lze zkontrolovat kliknutím na 3 tečky a zde v kontextovém menu vybrat Edit. Ujistite se, že změny uložíte přes tlačítko Save.

Po importu je potřeba upravit baseURL, jinak nebude fungovat nejen script, ale ani žádný request.

Poté je možné získat token přes endpoint /api/login/user. V těle requestu již budou předvyplněné hodnoty, které jsou ovšem pouze ukázkové a je třeba použít přihlašovací údaje existujícího uživatele v MS (váš klientsky účet).

CODE

{
  "login": "váš login do Mailshipu",
  "password": "vaše heslo do Mailshipu"
}

V případě úspěšného přihlášení je vrácen token, který je třeba posílat v hlavičce Authorization jako Bearer Token v rámci celé kolekce. Token z response si tedy zkopírujte. Vraťte se přes 3 tečky do kontextového menu a vyberte Edit - záložka Authorization. Vyberte jako typ Bearer Token. Pak už stačí jen do kolonky Token vložit zkopírovaný token (z endpointu /api/login/user).

Pozor! Každý token má omezenou platnost. Poté je třeba vygenerovat nový. Token uvedený v obrázku výše tedy nebude funkční.

Tímto nastavíte ověřování na celou kolekci. Bohužel, jednotlivé importované requesty mají ve výchozím stavu nastavené No auth. To je třeba změnit na hodnotu Inherit from parent. Nadřazené složky mají tuto hodnotu nastavenou automaticky, takže se ve výsledku použije autorizace z nastavení pro celou kolekci. Endpointy pro login ponechejte jako No auth, jinak si po expiraci nový token nevygenerujete.

Automatické ověřování

Postman umožňuje používat tzv. pre-request scripty, které se volají před zavoláním samotného requestu na API. Tyto scripty se píší v jazyce Javascript, a slouží primárně právě k získání ověřovacích tokenů.

Pro jejich nastavení se opět přepněte do editačního okna celé kolekce (3 tečky na kolekci → edit).

V záložce Pre-request Script vložte následující:

JavaScript

JS

const url = pm.variables.get('baseUrl');
const account = pm.variables.get('accountType');
const login = pm.variables.get('accountLogin');
const password = pm.variables.get('accountPassword');
const token = pm.variables.get('token');
const exp = pm.variables.get('tokenExp');
const now = (new Date()).getTime() / 1000;
 
if (token && exp && exp > now) {
    console.log('Token is up to date!');
} else {
    console.log('Fetching token...');
 
    const request = {
        url: url + '/api/login/' + account,
        method: 'POST',
        header: { 'content-type': 'application/json' },
        body: { mode: 'raw', raw: JSON.stringify({ login, password }) }
    };
 
    pm.sendRequest(request, (error, response) => {
        // on error
        if (response.code !== 200) {
            const { message } = response.json();
            console.log('Fetching failed: ' + message || 'Unknown reason');
            return;
        }
 
        // on success
        var { token, exp } = response.json();
        console.log('New token: ' + token);
        pm.environment.set('token', token);
        pm.environment.set('tokenExp', exp);
    });
}

Dále je třeba v záložce variables přidat doplňující proměnné a opět nezapomenout nastavení uložit:

AccountType je možné přepínat mezi admin a user. Podle typu účtu je potřeba vyplnit správné přihlašovací údaje k existujícímu účtu.

Nově získaný token se ukládá do proměnné {{token}}. Touto proměnnou lze nahradit náš první (napevno nastavený token) v záložce Authorization. Tím zajistíme, že se bude používat stále aktuální token získaný v prerequestu:

Jako poslední zbývá založit si nové prostředí (environment). V rámci prostředí se totiž ukládají získané tokeny. Díky tomu je možné se přepínat například mezi lokálním, testovacím a produkčním prostředí. Různá prostředí teoreticky mohou používat výchozí administrátorské účty se stejnými autentizačními údaji, ale tyto účty budou mít různé interní identifikátory, a tak je vygenerovaný token nepoužitelný v jiném prostředí, než v tom ve kterém byl vygenerován.

V prostředí (tzv. environment scope) se neukládá pouze token, ale i jeho expirace. Díky tomu se script nemusí stále ptát na nový token pro každý request, ale může používat stále stejný token, který obnoví až po jeho expiraci, čímž se ušetří zbytečné requesty navíc.

V prostředí je také možné přepsat (override) proměnné nastavené pro kolekci. Díky tomu je možné použít nejen jinou baseUrl, ale také třeba accountLogin + accountPasword, atd.

Více o nastavení prostředí je zde: https://learning.postman.com/docs/postman/variables-and-environments/managing-environments/