Popis API
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 budou 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.
Nastavení externího informačního systému
Nejprve je nutno si ve své organizaci v Sofa nastavit externí informační systém. Jde vlastně o nějakou vaši 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.
-
Po přihlášení do Sofa přejděte na stránku Administrace> API.
Pokud v nabídce položku API nevidíte, klepněte na horní liště na tlačítko se třemi tečkami.
-
Nyní je nutné vytvořit váš externí informační systém. Klepněte na tlačítko Vytvořit nový externí IS.
-
Vyplňte základní údaje o systému, tj. pole Název a Popis (zobrazují se pouze v rámci Sofa).
Nejdůležitější je heslo zapsané do pole Heslo, které bude sloužit k vygenerování přístupového 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 ! # $ % & ( ) * + , - . : = ? @ [ ] _ { | } ~).
Pro případné ladění problémů je vhodné nastavit si úroveň logování pro daný externí IS na Debug.
Po vyplnění všech údajů klepněte na tlačítko Registrovat.
-
Po uložení na řádku s položkou vytvořeného externího IS klepněte na tlačítko se třemi tečkami a poté na příkaz Upravit externí IS.
-
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 v bodu 3 slouží k autentizaci daného externího IS.