.. _viewapi_api:

=================
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ě.

.. _viewapi_api_init:

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=...`` 

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.


.. _viewapi_api_initfinised:

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:

.. code-block:: JSON

  {
    "type":"ViewInit"
  }



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 :ref:`dokončení inicializace <viewapi_api_initfinised>`.

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:

.. code-block:: JSON

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



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:

.. code-block:: JSON

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



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:

.. code-block:: JSON

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