Jak jsme zmínili v první části článku, dnes si EasyCargo API přiblížíme spíše z praktické stránky. K tomu využijeme našeho API klienta. Vyzkoušíme také fungování API pomocí online nástroje ReqBin. Ten umožňuje komunikaci s WWW serverem, díky kterému si můžeme stáhnout data, která nás zajímají, z našeho softwaru pro plánování nakládky EasyCargo.

Testování je jedna věc, ale v reálném životě možná používáte Java plugin pro váš software nebo volání funkcí Javascriptu ze SAPu. Více o této metodě, platformě Make a dalších praktických příkladech použití API v dalším díle této série.

 

EasyCargo API Klient

Podívejte se, jak výše uvedený požadavek vypadá v nástroji ReqBin

 

Obrázek výše ukazuje našeho API klienta pro EasyCargo. Aby bylo možné odesílat jakékoli requesty (požadavky) API na webový server, musí být klient nejprve autorizován. Požadavek na spuštění je tedy POST http://go.easycargo3d.com/api/v1/authenticationuživatelským jménemAPI klíčem. V odpovědi obdržíte ověřovací token ze serveru. Každý následující požadavek API (pokud není uvedeno jinak) by měl být ověřen přidáním získaného tokenu do jeho hlavičky. Zde stojí za zmínku, že všechny požadavky API jsou prováděny jménem vlastníka tokenu. Požadavky a odpovědi musí být vytvořeny ve formátu JSON nebo XML.

Autentizaci máme za sebou a nyní se přesuneme k zajímavějším kouzlům s API. Předpokládejme, že uživatel X má ve svém účtu uloženy následující nakládky:

 

Uložené nakládky pod konkrétním účtem v EasyCargu

Požadavky API si předvedeme právě na nich, jelikož nakládky jsou asi nejdůležitější součástí EasyCarga. Podobně jsou formulovány i další požadavky jako správa uživatelů, takže věříme, že po přečtení tohoto článku zvládnete podobné požadavky levou zadní. V dokumentaci API pro EasyCargo je popsána a vysvětlena každá metoda programovacího rozhraní. Máte-li jakékoli dotazy, určitě se nás neváhejte zeptat.

Požadavky API o nakládkách

Z dokumentace API se můžeme dočíst, že pomocí správně formulovaných požadavků můžeme ze serveru získat seznam všech nakládek a také údaje o konkrétní nakládce pod konkrétním účtem v EasyCargu. Můžeme dokonce vytvořit nebo odstranit nakládku z účtu.

Získání seznamu všech nakládek

 

Získání seznamu všech nakládek

Podívejte se, jak výše uvedený požadavek vypadá v nástroji ReqBin

 

Získání informací o konkrétní nakládce

 

Získání informací o konkrétní nakládce

Podívejte se, jak výše uvedený požadavek vypadá v nástroji ReqBin

 

Vytvoření nakládky

 

Vytvoření nakládky

Podívejte se, jak výše uvedený požadavek vypadá v nástroji ReqBin

 

Úspěšně vytvořená a uložená nakládka pomocí API v EasyCargu

Jak můžete vidět, nakládka byla úspěšně vytvořena a uložena na váš EasyCargo účet.

 

Naložení nakládky vytvořené pomocí API

V aplikaci můžete následně nově vytvořenou nakládku jednoduše otevřít.

 

Smazání nakládky

 

Smazání nakládky

Podívejte se, jak výše uvedený požadavek vypadá v nástroji ReqBin

 

Nakládky odstraněná z EasyCargo účtu pomocí API požadavku

Příslušným požadavkem byla nakládka odstraněna z vašeho účtu.

Ještě pár slov o API

  • Počet vašich požadavků API je časově omezen (60 požadavků za 1 hodinu). Kvóty jsou kontrolovány posunutím časového rámce, takže v daném časovém období je povolen pouze stanovený počet požadavků.
  • Chyby API jsou zasílány zpět běžnými stavovými kódy HTTP. Ve většině případů tělo odpovědi obsahuje konkrétní zprávu, co se pokazilo.
  • Prostřednictvím API nelze provést výpočet výsledného plánu nakládky. Vždy je zapotřebí člověka k tomu, aby se přihlásil do EasyCarga a stisknul tlačítko Naložit.
  • Váš klient rozhraní API musí podporovat přístup a úpravu hlavičky požadavku a odpovědi a analýzu dat ve formátu JSON nebo XML.
  • Aby mohl být zpracován výpočet výsledného plánu nakládky, uživatel API se musí přihlásit do EasyCarga.
  • Některé metody API podporují použití volitelných parametrů, například “from”. Význam každého z nich se dozvíte z dokumentace. Tyto parametry můžete použít například při požadavku na získání seznamu všech požadovaných nakládek. Parametry stačí přidat do adresy za “?” oddělené znakem “&” ve tvaru jméno=hodnota, např.: http://go.easycargo3d.com/api/v1/shipments?from=2020-01-02&offset=0&limit=100.

Jak jste se mohli sami přesvědčit, API je opravdu užitečná věc. Dnešní článek je druhým ze série o EasyCargo API, takže pokud jste ještě nečetli první díl, můžete to napravit zde. Ve třetím díle se dozvíte, jaké výhody má používání naší API, a ukážeme si také pár příkladů použití z reálného života.

Bartosz Ziółkowski | 14. Čvc 2022