Využití API v rámci Sofa

Základní informace

Co je to API – je to zkratka označení Application Programming Interface, kterou se v informatice označuje rozhraní pro programování aplikací. Úkolem API bude v našem případě zprostředkovat komunikaci dvou aplikací – tedy nějaké vaší aplikace s aplikací Sofa – a umožnit jejich vzájemnou výměnu dat.

Co je externí informační systém – jedná se vlastně o nějakou vaši aplikaci, která potřebuje komunikovat se Sofa, aniž byste museli zajišťovat návaznost v průběhu práce ručně. K tomu využívá rozhraní API.

Co je GraphQL – jedná se dotazovací jazyk pro tvorbu API vytvořený v roce 2012 společností Facebook. Od roku 2015 je GraphQL k dispozici jako open-source.

Co jsou dotazy – v GraphQL je nutné rozlišovat dva základní typy dotazů.

  • Prvním je query, obdoba SELECT z SQL. Jedná se typ dotazu, který se čistě dotazuje na uložená data a tato data žádným způsobem nemění. Spouštění query je tedy bezpečné, protože nemůže data žádným způsobem poškodit.

  • Druhým typem je mutation, což je obdoba SQL operací pro změnu dat a jejich struktury (INSERT, ALTER, DELETE, UPDATE…​). U provádění mutací je tedy nutné dbát na zvýšenou opatrnost a vědět, jak se daná mutace zachová. V případě spuštění špatné mutace lze nenávratně rozbít data.

Co je to JSON – jedná se o zkratku JavaScript Object Notation a jde o formát pro vzájemnou komunikaci a výměnu dat aplikací prostřednictvím rozhraní API. Proměnné, které budeme používat v GraphQL dotazech budou předávány právě ve tvaru objektů JSON.

Proměnné jsou definované v kulatých závorkách za názvem dotaz a značí se symbolem $. Je nutné uvést název proměnné a její typ. Povinné proměnné jsou označené vykřičníkem.
Příklad dotazu s definovanou povinnou proměnnou typu string: query findUserById($userIdent: String!). Příklady konkrétních dotazů i s proměnnými jsou uvedeny v kapitole Příklady jednoduchých GraphQL dotazů.

V GraphQL dotazu lze používat aliasy, je tedy možné si část příchozího JSON objektu pojmenovat podle potřeb. Toto může být velmi praktické například u vyhodnocování výsledku v rámci PAJS. Konkrétní příklad využití v Sofa bude popsán níže.

Vytvoření externího informačního systému

Nejprve je nutno ve vaší organizaci v Sofa vytvořit externí informační systém. Jde vlastně o systém přístupu k nějaké vaší aplikaci, která potřebuje komunikovat se Sofa, aniž byste museli zajišťovat vzájemný kontakt v průběhu práce ručně. K tomu se právě využívá rozhraní API.

  • V okně Administrace klepněte na tlačítko API.

vytvoreni1
Pokud tlačítko API nevidíte, klepněte na pravém konci lišty na tlačítko se třemi tečkami; zbytek ovladačů se zobrazí ve svislé nabídce.

  • Nyní je nutné vytvořit váš externí informační systém. Klepněte na tlačítko Vytvořit nový externí IS.

vytvoreni2

  • Vyplňte základní údaje o systému, tj. pole Název a Popis (zobrazují se pouze v rámci Sofa). Údaj v poli Identifikátor se vytvoří automaticky z řetězce zadaného do pole Název, lze ho ale v případě potřeby upravit.

  • Důležité je heslo zapsané do pole Heslo. To použijete při úpravách tohoto externího informačního systému, ale poslouží I při vygenerování tokenu pro přístup pomocí vytvořeného externího systému.

    Heslo musí být nejméně 8 znaků a nejvíce 64 znaků dlouhé, musí obsahovat minimálně jedno velké písmeno, jedno malé písmeno a jednu číslici. Povolené znaky jsou malá a velká písmena (a-z, A-Z), číslice (0-9) a speciální znaky (mezera ! # $ % & ( ) * + , - . : = ? @ [ ] _ { | } ~).

  • Úroveň zápisu informací o průběhu činnosti ExtIS nastavte pomocí voliče Úroveň logování nabízejícího možnosti Informace a Debug. Pro ladění problémů a chyb je vhodné nastavit si úroveň logování na Debug.

  • Pomocí zaškrtávacích políček nastavte oprávnění, která chcete externímu informačnímu systému přiznat. Budete-li chtít třeba externí IS využívat k dálkové správě uživatelů v Sofa, zaškrtněte políčko Může spravovat uživatele, skupiny a role.

  • Po vyplnění všech údajů klepněte na tlačítko Registrovat.

vytvoreni3

Položka vytvořeného externího informačního systému se zobrazí v okně API.

vytvoreni4

Dále klepněte na tlačítko se třemi tečkami na začátku položky. V rozvinuté nabídce spusťte příkaz Upravit externí IS.

vytvoreni5

V okně s popisem externího informačního systému je v poli Uživatel vygenerované uživatelské jméno, které v kombinaci s heslem zadaným při založení externího informačního systému poslouží k jeho autentizaci.

vytvoreni6