Všechny sbírky
Výukové články
API Ninja
API Ninja: Trénink 1/7 - Příprava testovacího prostředí
API Ninja: Trénink 1/7 - Příprava testovacího prostředí

V prvním tréninku se podíváme na přípravu testovacího prostředí pro API

Ota Rádl avatar
Autor: Ota Rádl
Aktualizováno před více než týdnem

Získané schopnosti:

  • přehled o možnostech pro volání webových služeb

  • orientace v příkazovém řádku

  • tvorba vlastního PHP skriptu

  • autentizace

Pro trénink API Flexi a jeho testování je možné využít několik přístupů a aplikací. Ukážeme si základní možnosti, kde vytrénovat svoje schopnosti až na API Ninju. Zároveň jsme pro Vás připravili vlastní testovací prostředí na adrese:

developer.flexibee.eu/c/ninja

Zde si můžete jednoduše testovat vlastní API triky.

Nejjednodušší možný přístup, který však využijeme pouze v případě čtení dat, je Váš webový prohlížeč. Zadáme požadavek do adresního řádku prohlížeče a přihlásíme se do Flexi standardním způsobem a získáme přesně data, která potřebujeme. Příklady si později ukážeme v úrovni Učeň, které zvládne opravdu každý. Pokročilé testování, včetně možnosti odesílat (zapisovat) data do ABRA Flexi, doporučujeme provádět v programu Postman.

V případě, že se cítíte jako Válečník a nechcete instalovat aplikaci Postman, nabízí se možnost trénovat pomocí příkazové řádky systému a nástroje cURL. cURL je rozšíření, pomocí kterého je možné do příkazového řádku (CMD, Terminál) přidat další příkazy. Pokud jste prozatím na úrovni Učeň, možná se Vám již točí hlava z toho, co čtete, ale nemějte strach, vše si ukážeme dále.

Opravdový API Ninja, s lehkou znalostí jazyka PHP, má možnost využít knihovnu HTTPFul. HTTPFul je PHP knihovna vyvinutá pro jednoduchou a elegantní komunikaci s API různých aplikací. S využitím této knihovny a jazyka PHP je možné vytvořit vlastní chytré skripty, spustitelné například uživatelským tlačítkem. O tom více později v samostatném tréninku.

A nyní si již ukážeme jednotlivá tréninková prostředí dle úrovně.

Úroveň: Učeň

Pro učně doporučujeme dva mocné pomocníky na API bojišti. Se čtením dat z Flexi nám pomůže webový prohlížeč. Ještě mocnější spolubojovník Postman nám pomůže i s nejsložitějším chvatem, co se týče zápisu a úpravy dat ve Flexi.

Využití webového prohlížeče

Neexistuje jednodušší způsob, jak získat konkrétní záznam nebo sadu záznamů z ABRA Flexi, aniž bychom spouštěli Flexi aplikaci, zdlouhavě klikali a filtrovali, než se dostaneme k tomu, co potřebujeme. Stačí využít jakýkoliv webový prohlížeč, na který jste zvyklí. Co si například stáhnout faktury po splatnosti do PDF nebo Excelu jedním kliknutím? Vyzkoušejte.

Přistupte pomocí Vašeho webového prohlížeče na tyto adresy:

https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat%3Cnow()).pdf?report-name=fakturaKB

https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat%3Cnow()).xls?detail=custom:kod&limit=0

Zvídavý učeň si všimne, že v adresním řádku webového prohlížeče se občas objeví znaky s procenty, například %3C. To z důvodu zakódování URL pro webový prohlížeč, který nepovoluje speciální znaky a mezery v adrese. Více si povíme v tréninku sestavování URL.


Z první adresy získáme PDF sestavu všech faktur po splatnosti. Z druhého odkazu pak stáhneme Excel tabulku s kódy všech faktur, které jsou k dnešnímu dni po splatnosti. Těmito jednoduchými triky lze získat přehled potřebných dat. Odkaz je možné si upravit pro svoji licenci a uložit do záložky prohlížeče. Jednoduché, že, učedníku? Užitečných příkladů se najde celá řada, jistě Tě napadnou další.
​

Webový prohlížeč bohužel nezvládne všechny triky.

Webový prohlížeč není plnohodnotné testovací prostředí. Poslouží pouze v případě, že chceme rychle číst konkrétní data z Flexi. Pokud bychom chtěli například faktury upravit, změnit datum upomenutí, musíme k adrese ještě zaslat tělo požadavku metodou POST. K tomu nám poslouží aplikace Postman.
​

Aplikace Postman

Postman je spolehlivým společníkem každého API Učně. Nabízí jednoduché grafické rozhraní a pomůže vám tak provádět i nejsložitější API triky a chvaty. Podíváme se tedy, jak s ním spolupracovat. Postman je volně ke stažení na adrese GetPostman, případně lze přidat jako rozšíření do Google Chrome, doporučujeme však plnohodnotnou desktop aplikaci.

Po úspěšné instalaci se důkladně zorientujte v prostředí aplikace. Pro jakoukoliv operaci je nejprve nutná autentizace uživatele, učiníte tak na záložce Auth, kde vyplníte Vaše přihlašovací údaje.

Pro náš API trénink postačí typ Basic Auth, což je běžná HTTP autentizace. Slovy pro učně - obdobné přihlášení jako přímo do webového rozhraní Flexi. Samozřejmě je možný i jiný typ autentizace, což je však za hranicemi poznání na úrovni Učeň.

Nyní se zaměříme na nejdůležitější oblast v rozhraní Postmana. Soustřeďte se na číslované oblasti, vysvětlivky jsou popsány níže. Těchto několik bodů musí každý Učeň využívající Postmana znát i při půlnočním cvičném API chvatu.

Těžko na cvičišti, lehko na bojišti!

1) Výběr HTTP operace

  • Postman nabízí širokou škálu podporovaných operací, nicméně pro práci s Flexi nám momentálně postačí základní metody HTTP - GET, POST, PUT, DELETE

Pro zvídavé učně více informací zde
​

2) Pole pro zadání URL adresy, s kterou bude Postman pracovat

3) Výběr formátu, ve kterém budou data posílána na danou URL

  • tato oblast se nás týká pouze v případě, že budeme data zasílat

  • POZOR – příponu URL adresy je nutné uvádět shodnou s formátem zasílaných dat

4) Výběr podoby vytvářeného requestu (standardně raw)

  • tato oblast souvisí s oblastí 3 a taktéž nás zajímá v případě odesílání dat

5) Oblast pro odpověď

  • Flexi při volání API komunikuje zpět, tedy v této oblasti se nám zobrazí odpověď (response) Flexi, pokud jsme žádali data, případně o průběhu požadavku, zda proběhl v pořádku nebo s chybou, v případě, že jsme zasílali data do ABRA Flexi

6) Tělo požadavku (request)

  • zde zapisujeme obsah svého požadavku v případě zasílání dat do Flexi, například ve formátu XML/JSON

Příklad mluví za vše, vyzkoušíme se tedy první chvat v Postmanovi. V záložce Auth vyplňte své přihlašovací údaje (Kde je vezmu?). Vyberte HTTP operaci GET na adresu https://developer.flexibee.eu:5434/c/ninja/faktura-vydana.xml.

A zapište raw tělo požadavku, ve formátu XML (application/xml) s následujícím obsahem:

<?xml version="1.0" encoding="utf-8"?> 
  <winstrom version="1.0"> 
   <faktura-vydana> 
     <typDokl>code:FAKTURA</typDokl> 
     <firma>code:FLEXI</firma> 
     <popis>Ninja faktura z CURL</popis
     <sumZklZakl>1000.0</sumZklZakl> 
     <bezPolozek>true</bezPolozek> 
   </faktura-vydana>
  </winstrom>

Zbývá Send! Success: true? Ano, učedníku, právě si vytvořil fakturu ve Flexi pomocí API. Postman veškeré příkazy ukládá do historie, kdykoliv se k nim můžeš vrátit.

Postman toho umí samozřejmě více, vydej se na průzkum, učedníku.

Úroveň: Válečník

Bojovník jistě využije variantu, pro kterou není nutná instalace aplikace s grafickým rozhraním a vystačí si s příkazovým řádkem, pomocí kterého může data získat i zaslat do ABRA Flexi.

cURL

cURL je příkaz, který umožňuje snadno stáhnout data z libovolné adresy, ale také je možné pomocí něho data odeslat na zadanou adresu. cURL je možné získat pro Váš systém na adrese https://curl.haxx.se/. V sekci Download naleznete obsáhlou řadu verzí, vyberte si vhodnou podle Vašeho operačního systému.

Na stránkách získáte také informace o instalaci v závislosti na Vašem systému. V případě Linuxu postačí pomocí příkazové řádky provést instalaci dle vaší distribuce. V případě Windows bude pravděpodobně potřeba nastavit systémovou proměnnou PATH. MacOS X obsahují cURL již v základu a je možné jej začít hned používat.

Utáhni opasek, bojovníku, jdeme na to!

Pokud máte připravený cURL, vrhneme se do příkazové řádky neboli “cmd” na Windows, “terminál” na Linux a Mac. Základní příkaz vypadá následovně:

curl -u jmeno:heslo -L -o soubor.pdf

  • -u určuje autorizační údaje do Flexi.

  • -L následuje přesměrování. Pokud v budoucnosti dojde ke změně struktury URL, tento příkaz zajistí, že skript bude stále fungovat.

  • -o zaručí, že vrácená data budou zapsána do souboru “soubor.pdf”.

  • -f určuje, že pokud na straně serveru nastane chyba, nemá se nic zapisovat do výstupu, ale hned ukončit.

  • -k pokud používáte vlastní instalaci a automaticky generovaný certifikát, je nutné ignorovat nedůvěryhodnou certifikační autoritu.

  • -T zasílaný soubor (tělo požadavku)

Více informací o skladbě příkazů získáte pomocí příkazu “curl --help”.

Správný trénink si žádá vyzkoušet nějaké triky. Například získání všech neuhrazených faktur do PDF souboru je možné následujícím příkazem:

curl -u login:heslo -k -L -f "https://developer.flexibee.eu:5434/c/ninja/faktura-vydana/(stavUhrK%20!=%20%27stavUhr.uhrazeno%27).pdf" -o neuhrazene-faktury.pdf

Samozřejmě je nutné namísto login:heslo uvést Vaše přihlašovací údaje, které získáte pomocí formuláře na konci prvního článku API Ninja seriálu. PDF soubor neuhrazene-faktury.pdf se uloží do složky, kde se zrovna nacházíte v příkazové řádce.

Dokážeš uložit soubor jinam, válečníku?

Čtení je tedy velmi jednoduché, obdobně je to i se zápisem do Flexi. Uvažujme tvorbu faktury. Abychom mohli vytvořit fakturu, budeme nejdříve potřebovat XML soubor s daty. Vytvořte soubor faktura.xml s následujícím obsahem:
​

<?xml version="1.0" encoding="utf-8"?> 
 <winstrom version="1.0"> 
  <faktura-vydana> 
   <typDokl>code:FAKTURA</typDokl> 
   <firma>code:FLEXI</firma> 
   <popis>Ninja faktura z CURL</popis> 
   <sumZklZakl>1000.0</sumZklZakl> 
   <bezPolozek>true</bezPolozek> 
  </faktura-vydana> 
 </winstrom>

Poté zbývá zavolat cURL příkaz z místa v příkazové řádce, kde je uložen vytvořený soubor. Odpověď Flexi získáte zpět do příkazového řádku.

curl -u login:heslo -k -L https://developer.flexibee.eu:5434/c/ninja/faktura-vydana.xml -T faktura.xml

Cítíš, že máš na víc, válečníku? Nebojíš se vkročit do oblasti PHP? Vyzkoušej úroveň Ninja a zařaď se hned v prvním tréninku do elitní úrovně API Ninja.
​

Úroveň: Ninja

Ninja bojovník nikoho dalšího nepotřebuje. Vytvoří si své vybavení a cvičiště sám. K tomu může posloužit HTTPFul.

HTTPFul

HTTPFul je PHP knihovna, která umožňuje jednoduše komunikovat pomocí HTTP protokolu v PHP prostředí. Tvůrce knihovny uvádí na svých stránkách i možnosti, jak knihovnu nainstalovat. Samozřejmě je potřeba mít na svém počítači zprovozněné PHP prostředí.

Pro naše potřeby tréninku bude nejvhodnější instalace variantou číslo 1. Stažený soubor pouze přiřadíme k našemu skriptu:

<?php 
//Cesta ke staženému souboru include('./httpful.phar'); 
... 
?>

Poté můžeme pokračovat v našem skriptu, který obsahuje HTTPFul volání API Flexi a poté výsledek vypíšeme na obrazovku:

<?php 
$flexiLogin = 'ninja'; 
$flexiHeslo = 1234; 
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat%3Cnow()).xml?limit=0; 

$response = \Httpful\Request::get($uri) 
 ->expectsXML() 
 ->authenticateWith($flexiLogin, $flexiHeslo) 
 ->send(); 

echo $response->body->winstrom->{'faktura-vydana'}; 
... 
?>

Takto nejjednodušeji získáme XML všech faktur po splatnosti. Pokud budeme chtít nějaké data do Flexi zaslat pomocí HTTPFul nejprve si data připravíme v XML/JSON formátu. Pro PHP využijeme nejlépe formát JSON, který je možné jednoduše vytvořit z PHP pole.

A opět zavoláme HTTPFul na pomoc s metodou POST:

<?php 
$idFaktury = 1; 
$faktura['winstrom']['faktura-vydana']['id'] = $idFaktury; $faktura['winstrom']['faktura-vydana']['varSym'] = '123456789'; 
$json = json_encode($faktura); 
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana.json'; 
$response = \Httpful\Request::post($uri) 
  ->sendsJson()
  ->authenticateWith($flexiLogin, $flexiHeslo) 
  ->send(); 
... 
?>

Tímto skriptem jsme vybrané faktuře změnili variabilní symbol. Základy použití knihovny jako nástroje pro přístup k API Flexi jsme si ukázali. Skutečný API Ninja se lehkou znalostí PHP obohatí skripty o potřebná rozšíření, jak předat hodnoty či zpracovat výsledky, to už však necháme na vaší tvořivosti.

Seznamte se důkladně s vybraným testovacím prostředím. V příštím tréninku nás již čeká teorie o struktuře a sestavování URL.


​

Dostali jste odpověď na svou otázku?