Podrobný popis API

Tvorba rozhraní

Vývojář externí aplikace, ke které má být Maatrix připojen, potřebuje provést dva základní kroky:

Krok 1 - příprava rozhraní na straně externí aplikace

Vývojář musí vytvořit na straně své aplikace prostředí, které bude umět odeslat a následně také načíst data ve formátu podporovaném Maatrixem a umět je odesílat a přijímat některým z protokolů systému Maatrix - více informací naleznete zde.

Krok 2 - získání InterfaceID - klíče do API Maatrixu

Získat ID pro rozhraní své aplikace (InterfaceID). Může použít univerzální registraci do tzv. open rozhraní. Takové rozhraní pak není registrováno na žádného aplikačního partnera. V tomto případě je InterfaceID=int-key-u3b

Tato univerzální registrace má některá důležitá omezení:

  • Při použití otevřeného rozhraní nemůže administrátor služby Maatrix omezit aplikace, které mohou jeho službu spouštět (místo InterfaceID pro konkrétní externí aplikaci musí použít povolení pro toto univerzální rozhraní) - snižuje se tak bezpečnost API. 
  • Při bezpečnostním incidentu - případném útoku na toto univerzální rozhraní - může být toto univerzální rozhraní dočasně zablokováno.
  • Registrace vlastního rozhraní pro externí aplikaci (vlastní InterfaceID) umožní vývojáři testovací provoz při vývoji své aplikace

Druhá možnost je tedy vytvořit si vlastní registraci svého rozhraní. To se provede následujícím postupem:

Krok a

V systému Maatrix je založen zákazník (firma vyvíjející externí aplikaci) a je založena jedna nebo více komunikačních služeb (pro které má být rozhraní vytvořeno). Postup založení zákazníka a komunikační služby naleznete zde.

Krok b

Firma vyvíjející externí aplikaci požádá poskytovatele systému Maatrix (firmu Maat) o status aplikačního partnera (kontakty naleznete zde)

Krok c

Po té, co je zákazník nastaven poskytovatelem aplikace (firmou Maat) na status aplikačního partnera, je v portále systému Maatrix u nastavení údajů zákazníka k dispozici záložka rozhraní (viz. obrázek níže). Zde může vývojář rozhraní definovat a spravovat jedno či více rozhraní. Podrobnější informace o tom, jak spolupracuje externí aplikace se systémem Maatrix naleznete zde.

interface app partner sl

Krok d

Vývojář si v této záložce může tlačítkem PŘIDAT založit registraci rozhraní ke své externí aplikaci. Je vygenerován 9-ti místný identifikační kód registrace (v podobě int-xxx-xxx), který slouží jako základní identifikátor rozhraní pro komunikaci aplikací daného aplikačního partnera se systémem Maatrix (InterfaceID).

Krok e

Vývojář si pojmenuje rozhraní ke své aplikaci. Tento název je viditelný pro všechny další zákazníky, kteří mohou rozhraní k této aplikaci použít. Je tedy potřeba zvolit takový název, aby co nejlépe vystihoval připojení na konkrétní externí aplikaci, tj. v názvu by měl být název externí aplikace, firmy vyvíjející nebo dodávající tuto aplikaci popřípadě další doplňující informace. Poskytovatel systému Maatrix si v případě nejednoznačnosti vyhrazuje právo tento název dodatečně měnit.

Krok f

Vývojář si vybere jeden z nabízených typů rozhraní. Typ rozhraní je způsob připojení na systém Maatrix a definuje kombinaci protokolu a formátu, ve kterém chce vývojář se svojí aplikací se systémem Maatrix komunikovat. O protokolech a formátech naleznete více zde, o typech rozhraní vč. jejich popisů naleznete více zde.

Krok g

Stav nově založeného rozhraní je automaticky nastaven na development. Tento stav slouží pro vývoj a ověření základní komunikace mezi externí aplikací a systémem. Pokud je rozhraní v tomto stavu, externí aplikace musí se systémem Maatrix komunikovat v tzv. SandBoxu (více informací naleznete zde), systém Maatrix kontroluje pouze základní identifikátory a formát zaslané věty. V tomto stavu není možné spustit konkrétní komunikační službu. Údaje týkající se identifikace služby, M2M heslo a vstupní parametry služby tak v této fázi nemusí být uvedeny a nebo mohou obsahovat libovolné hodnoty.

Krok h

Pokud bude kontrola formátu vět zaslaných z rozhraní ve stavu development v pořádku (Response = OK), je vývojáři rozhraní umožněno změnit stav rozhraní na testing. V tomto stavu se již nekomunikuje v SandBoxu, ale data se již zasílají na produkční vstupní adresy (více informací naleznete zde) a rozhraní ve stavu testing může spouštět, řídit a dotazovat se na konkrétní komunikační služby - v tomto stavu rozhraní to však mohou být pouze služby, které si registroval zákazník - aplikační partner (tj. stále ještě není možné rozhraní použít u jiného zákazníka). V tuto chvíli už musí být správně i všechny náležitosti týkající se konkrétní komunikační služby (tj. služba musí být nastavena tak, aby byla spustitelná tímto rozhraním, a hodnoty zasílané prostřednictvím interface musí odpovídat nastavení této služby - více informací naleznete zde). Po prvním řádném volání služby je vývojáři rozhraní umožněno změnit stav rozhraní na open. V tuto chvíli již mohou rozhraní využívat i ostatní zákazníci systému Maatrix.

Krok i

Vývojář rozhraní může měnit název, popis, typ a stav rozhraní kdykoli v průběhu vývoje rozhraní. V okamžiku, kdy rozhraní bude použito u první komunikační služby u jiného zákazníka, než je aplikační partner, je možnost změny názvu, typu a stavu znemožněna. Od této chvíle může tyto údaje měnit pouze poskytovatel systému Maatrix (firma Maat).

Krok j

Aplikační partner může s poskytovatelem systému firmou Maat dojednat definici šablon, pro které smí být rozhraní použito (a to včetně tvorby nové šablony komunikační služby určené pouze pro konkrétní externí aplikaci), může dojednat omezení použití tohoto rozhraní pouze pro předem definované zákazníky systému Maatrix.