Než začnete sestavovat vlastní požadavky, potřebujete nástroj, kterým je odešlete. V tomto díle si ukážeme program Postman, ve kterém na podpoře Flexi provádíme veškeré testování, a projdeme si přihlášení uživatele.
Čím REST API volat
Pro seznámení s API a pro testování doporučujeme Postman. Nabízí přehledné grafické rozhraní, ve kterém snadno sestavíte i složitější požadavek a rovnou uvidíte odpověď serveru. Je volně ke stažení na stránkách výrobce, doporučujeme desktopovou aplikaci.
Postman ale není jediná cesta. Data lze číst i přímo v prohlížeči, odesílat požadavky z příkazové řádky nástrojem cURL nebo napsat vlastní skript. Ostrá integrace Flexi s jiným systémem bude nakonec vždy stát na vlastním kódu, pro seznámení s rozhraním a pro ladění je však Postman nejrychlejší.
💡 Jednotlivé nástroje si můžete prakticky vyzkoušet v seriálu API Ninja, který k tomu má připravené vlastní testovací prostředí.
Přihlášení uživatele
Pro jakoukoliv operaci je nejprve nutné se přihlásit. V Postmanu k tomu slouží záložka Authorization (ve starších verzích Auth), kde vyplníte přihlašovací údaje. Pro testování postačí typ Basic Auth.
Pokud chcete daného uživatele používat výhradně pro přístup přes REST API, založte si uživatele pro API. Přístup k API se pořizuje samostatně a stojí tolik, co jeden standardní přístup dané varianty licence; počet API uživatelů pak už omezený není. Podrobnosti popisuje článek o licencování přístupu k API, ceny najdete v ceníku.
⚠️ Přihlašovací údaje posílejte vždy přes HTTPS a nikdy je neuvádějte přímo v URL adrese. V URL se ukládají do logů serveru i do historie prohlížeče. Uživateli pro API zároveň nastavte jen ta práva, která integrace opravdu potřebuje.
Basic Auth je nejjednodušší způsob přihlášení a pro seznámení s API stačí. Pro dlouhodobě běžící integrace se hodí spíš JSON autentizace, kdy si jednou vyžádáte autentizační token a ten pak posíláte s dalšími požadavky. Oba způsoby, včetně přihlašování přes SAMLv2 a OpenID, popisuje článek o autentizaci.
Rozhraní Postmanu krok za krokem
Následující oblasti rozhraní budete potřebovat u každého požadavku.
1. Výběr HTTP operace
Postman nabízí širokou škálu operací, pro práci s Flexi vystačíte se třemi: GET, POST a PUT. Jejich význam si vysvětlíme v díle o čtení, zápisu a mazání záznamů.
2. Pole pro zadání URL adresy
Sem zapíšete adresu, se kterou bude Postman pracovat. Způsob, jak ji poskládat, popisuje díl o sestavování URL adresy.
3. Formát odesílaných dat
Tato oblast se uplatní jen tehdy, když data do Flexi zapisujete.
⚠️ Příponu URL adresy uvádějte shodnou s formátem zasílaných dat. Pokud pošlete XML na adresu končící na .json, požadavek skončí chybou.
4. Podoba vytvářeného požadavku
Souvisí s předchozím bodem a týká se opět jen odesílání dat. Standardně vyberte raw.
5. Odpověď serveru
Zde se po odeslání zobrazí odpověď Flexi:
u operace
GETjsou to požadovaná data ve zvoleném formátu, typicky XML nebo JSONu operací
POSTaPUTje to výsledek operace, tedy zda proběhla v pořádku, a identifikátor dotčeného záznamu
6. Tělo požadavku
Do této oblasti zapisujete obsah požadavku ve formátu XML nebo JSON, tedy data, která chcete do Flexi uložit.
Uvedený příklad vytvoří vydanou fakturu s kódem TESTFAKTURA, typem dokladu FAKTURA (standardní faktura), vystavenou 1. 1. 2018 a s variabilním symbolem 20180101. Další příklady najdete v posledním díle série.
Další díly série
Postman a přihlášení uživatele (tento článek)