7.2. Popis rozhraní

API umožňuje zobrazení komponenty z archivního balíčku v samostatném rámci prohlížeče. API je navrženo pro integraci v prohlížeči formou interakce mezi stránkou z aplikace pro zpracování a stránkou poskytující zobrazení komponent digitálního archivu. Jedná se tak o přímou frontendovou integraci bez samostatného kanálu mezi serverovými (backendovými) částmi aplikací. Výhodou tohoto přístupu je nízká náročnost implementace. Za jistou nevýhodu je možné považovat nemožnost pokročilejších forem integrace, a to například interakce s jiným typem aplikací, než jsou webové aplikace, či hlubší propojení metod autentizace.

Služba pro zobrazení komponenty se inicializuje otevřením rámce (IFRAME) a předáním parametrů (požadavek typu GET). Dále se zasílají zprávy mezi rodičovským oknem a vnořeným rámcem, které umožňují dále řídit zobrazení a případně ho parametrizovat.

Typická interakce pomocí API mezi zpracovávající aplikací (klient) a implementací API na straně digitálního archivu (server):

(Klient → Server) Inicializace rámce (GET s parametry)
(Server → Klient) Potvrzení o dokončení incializace, případně předání informace o chybě (oprávnění apod.)
(Klient → Server) Zaslání požadavku na zobrazení komponenty
(Server → Klient) Informace o aktuálně zobrazené komponentě

Oboustranná komunikace mezi klientem a serverem umožňuje parametrizovat zobrazení, dostávat informace o jeho stavu a vykreslovat informace o aktuálně zobrazované komponentě či případné chybě.

7.2.1. Inicializace rámce

Klient otevře URL pro zobrazení serveru v elementu IFRAME. Jako parametry URL se předává:

(povinně) zdrojové URL, odkud je server volán, je nutné pro řešení CORS, parametr: SOURCE_ORIGIN=...

7.2.2. Společné vlastnosti zpráv

Zprávy jsou zasílány jako JSON objekty. Každá zpráva je určena svým typem v atributu type.

Zpráva může být rozšířena o volitelný atribut messageId umožňující její identifikaci na straně příjemce a zapsání do logu. Hodnota by měla být typu string.

7.2.3. Dokončení inicializace

Směr: Server → Klient

Zaslání zprávy ze zobrazovací aplikace DA (server) do rodičovského rámce (klient) o dokončení inicializace.

Typ zprávy: type: ViewInit

Příklad:

{
  "type":"ViewInit"
}

7.2.4. Zobrazení komponenty

Směr: Klient → Server

Odeslání identifikátorů komponenty z klientské aplikace do aplikace pro zobrazení. Klient může zprávu zaslat až po obdržení zprávy o dokončení inicializace.

Parametry zprávy jsou:

Typ zprávy: type: ViewRequest

Volitelná identifikace požadavku, vrací se zpět po dokončení editace: requestId: string

Identifikátor balíčku: daoId: ...

Identifikátor komponenty v balíčku: entityRef: ....

Příklad:

{
  "type":"ViewRequest",
  "requestId":"itemId=423456",
  "daoId":"de450515-98c3-4710-9d0d-bf227bfa875f",
  "entityRef":"uuid-d68bc931-9d71-4188-8931-c5816099f7bd"
}

7.2.5. Zaslání notifikace o zobrazené komponentě

Směr: Server → Klient

Zobrazení komponenty z digitálního archivu může trvat určitou dobu, může skončit úspěšně i chybou. Aby bylo možné uživateli efektivně zobrazovat informaci o aktuálně zobrazeném balíčku, komponentě a jeho kontextu, je vždy zaslána zpět zpráva o aktuálně zobrazené komponentě.

Parametry zprávy jsou:

Typ zprávy: type: ActiveView

Volitelná identifikace požadavku, vrací se zpět, pokud byla předána s požadavkem na zobrazení: requestId: string

Identifikátor balíčku: daoId: ...

Identifikátor komponenty v balíčku: entityRef: ....

Příklad:

{
  "type":"ActiveView",
  "requestId":"itemId=423456",
  "daoId":"de450515-98c3-4710-9d0d-bf227bfa875f",
  "entityRef":"uuid-d68bc931-9d71-4188-8931-c5816099f7bd"
}

7.2.6. Zaslání zprávy o chybě

Směr: Server → Klient

Zpráva umožňuje předat informaci o chybě ze strany serveru do klienta. Scénáře pro použití: chybně předaná data z klienta/aplikace a další.

Parametry zprávy jsou:

Typ zprávy: type: ViewError

Chybová zpráva: message: string

Volitelné upřesnění chyby: description: string

Příklad:

{
  "type":"ViewError",
  "message":"Chyba",
  "description":"Popis chyby"
}