ABRA Software a.s.

Testujeme WebAPI ABRA Gen v aplikaci Postman, díl 1.

Testujeme WebAPI ABRA Gen v aplikaci Postman, díl 1.

Štítky: APIAPI seriál

Irena Nováková / Ilustrace: getpostman.com / 5.1.2017

minulém díle jsme si API krátce představili a řekli si, na jakém principu funguje. Dnes si ukážeme praktické příklady. Testování WebAPI jsme provedli v aplikaci Postman – nástroji pro vývojáře, který slouží k objevování a testování API možností. 

WebAPI je postavené na principech REST rozhraní. Pro komunikaci tedy používá webový protokol HTTP, který funguje na principu požadavku a odpovědi. Požadavek i odpověď mají podobu textové zprávy, která se skládá z hlavičky a volitelně obsahu (závisí na typu zprávy). V hlavičce požadavku je obsažena především identifikace tzv. zdroje, tedy entity, které se požadavek týká. Zdroj je jednoznačně identifikován tzv. URL (Uniform Resource Locator).

V hlavičce se nachází metoda respektive operace, kterou chceme s konkrétním zdrojem dat provést – GET (získat), POST (vytvořit), PUT (aktualizovat), DELETE (smazat). Server posílá odpovědi ve formě textové zprávy, která obsahuje hlavičku a případně tělo. V hlavičce je uveden status kód, který představuje typ odpovědi (zda byl požadavek zpracován úspěšně, jestli došlo k chybě apod.). Sdělení v tomto případě reprezentují celá čísla (například 200 představuje úspěšné splnění požadavku, 201 znamená vytvoření nového obsahu, atd.). V těle odpovědi jsou pak data, o která uživatel požádal.


Ukázka v aplikaci Postman

Abychom si mohli ukázat příklady na práci s WebAPI, budeme potřebovat nějakého rozumného HTTP klienta. Pro testování REST API se nám osvědčila aplikace Postman. Všechny požadavky, které budeme odesílat do WebAPI, musí být autentifikované metodou Basic Auth. Při zadání požadavku v Postmanu tedy musíme nastavit na záložce „Authorization“ typ autorizace a zadat uživatelské jméno a heslo. A samozřejmě mít povolený přístup přes WebAPI v ABRA Gen.

Struktura URL

Adresa (URL) požadavků, které budeme posílat do WebAPI, má následující strukturu:

{protokol}://{server}[:port]/{spojeni}/{kontrolér}[/{cesta}][?{parametry}]

Příklad: Když chceme vytvořit požadavek pro získání ID, kódu a názvu všech firem použijeme tuto URL: 

http://localhost/data/firms/views/all?select=ID,Code,Name

Protokol je v tomto případě http (další možností je https pro zabezpečené připojení) a v dalším textu budeme uvádět URL bez něj. Název server je počítač, na kterém pracujeme. Port neuvádíme - jedná se tedy o výchozí port pro daný protokol (80 pro http, 443 pro https). Jako název spojení jsme použili data. Kontrolér se typicky jmenuje jako název třídy business objektu v množném čísle (firms, storecards, issuedinvoices atd.). Volitelně zadaná cesta určuje specifický zdroj, o který se kontrolér stará. V tomto příkladě je cesta /views/all, což je speciální pohled na seznam firem, který obsahuje všechny firmy včetně skrytých a předchůdců. Za otazníkem jsou uvedené parametry, v našem příkladě se jedná o parametr dotazovacího jazyka select, kterým se určuje, jaké položky z business objektu chceme vrátit.

Formát JSON

Všechna strukturovaná data, se kterými naše WebAPI pracuje, jsou uložená ve formátu JSON (JavaScript Object Notation). Autorem jednoho z nejpoužívanějších formátů pro výměnu dat na webu je americký programátor Douglas Crockford, který se v roce 2000 zasloužil o jeho masové rozšíření. Pro zápis krátkých strukturovných dat totiž JSON ve srovnání s XML funguje lépe – práce s ním je jednodušší a elegantnější. Například seznam objektů je reprezentován jako pole objektů:

[{
  "ID":"3200000101", 
  "Code":"111",
  "Name":"Všeobecná zdravotní pojišťovna ČR"
 },
 {
  "ID":"1100000101",
  "Code":"00022",
  "Name":"TeerCorporation"
 },
 ...
]

Na stejném principu funguje požadavek, kdy chceme vytvořit nový nebo změnit existující business objekt – data business objektu posíláme na server ve formě JSON objektu, například:

[{
  "code":"foo",
  "Name":"Foo, a. s."
}]

Tím pro dnešek končíme a budeme se těšit příště. V dalším díle se zaměříme na odesílání požadavků metodou GET, POST, PUT a DELETE. 

Přehled celého seriálu najdete v rubrice WebAPI ABRA Gen.