.. _baseapi_impl: ========================== Implementační doporučení ========================== Při implementaci komunikačního rozhraní je vhodné zvážit aspekty popsané v této kapitole. Jedná se o několik doporučení k možnému způsobu implementace. .. _baseapi_impl_updates: Dostupné balíčky a zjišťování změn ===================================== V :ref:`REST rozhraní ` je pro zjištění dostupných balíčků v digitálním archivu funkce ``GET /updates``. Funkce se volá opakovaně s parametrem ``nextQuery`` pro zjištění dalších změn. Hodnota parametru je vrácena vždy z předchozího volání uvedené funkce. Jedná se o řetězec a jeho vnitřní struktura a obsah jsou plně na implementujícím digitálním archivu. Požadavky na parametr ``nextQuery``: - hodnota platná bez časového omezení - není určen pro interpretaci na klientovi - musí zaručovat poskytnutí všech změnových informací z DA Funkce ``GET /updates`` nepodporuje klasické stránkování. Informace o pozici, pokud je potřebná, musí být zakódována uvnitř parametru ``nextQuery``, nebo ji pro daný **iterátor** musí uchovávat DA. Dále jsou uvedeny příklady možných implementačních přístupů: .. _baseapi_impl_updates_trans: Digitální archiv s transakční historií ----------------------------------------- **Předpoklad**: V digitálním archivu je dostupná tabulka s transakční historií, tj. při každém zápisu či změně do digitálního archivu vzniká záznam o transakci, který má jednoznačný identifikátor. Obsah ``nextQuery`` je potom možné sestavit jako kombinaci hodnot ``from:,to:,pos:``. Na základě hodnot *transakce od* a *transakce do* je možné sestavit **uspořádaný** seznam změněných balíčků. Uspořádanost seznamu změn je významná, aby bylo možné vracet informace o změnách postupně a nedocházelo k jejich přeskupování v rámci pořadí. Hodnota *pozice* umožňuje určit, kolik z daného rozsahu změn již bylo předáno, resp. která poslední změna byla předána. Digitální archiv s notifikacemi o změnách ---------------------------------------------- **Předpoklad**: V digitálním archivu je při změně balíčku vyvolána událost, na níž je možné reagovat v aplikační komponentě. Způsob předávání těchto notifikací není významný. Informace o přijatých notifikacích je možné zapisovat do databáze a očíslovat je vzestupnou řadou čísel. Obsah ``nextQuery`` potom tvoří vždy uvedené pořadové číslo poslední předané změny. Digitální archiv s iterátory ---------------------------------------------- **Předpoklad**: Pro každého připojeného klienta bude vytvářen samostatný iterátor. Jeho hodnota bude svázána s účtem pro synchronizaci. Hodnota nextQuery může mít charakter *iterátoru* a jeho hodnota bude nastavována vždy samostatně pro každého připojeného klienta. Způsob implementace iterátoru závisí na použité technologii při implementaci. Iterátor není platný pro více uživatelů, ale bývá samostatně vytvářen pro jednotlivé připojované systémy a jejich účty. Implementačně se může jednat například o samostatnou tabulku v databázi, do níž jsou zaznamenávány jednotlivé záznamy o změnách. Tyto záznamy čekají na předání danému klientovi. Při příštím vyžádání dalších změn je možné odstranit předchozí již předané záznamy. Změna rozsahu oprávnění ========================= Na základě příslušného uživatelského oprávnění má uživatel dostupnou sadu balíčků prostřednictvím API uložených v digitálním archivu. V případě změny rozsahu oprávnění by měla existovat možnost, jak získat seznam nově zpřístupněných balíčků. Příkladem takové situace může být umožnění přístupu k třídě balíčků, které v DA existují, ale doposud k nim uživatel neměl oprávnění. Podstatné je, že při zpřístupnění balíčků na základě změny oprávnění nedochází k jejich změnám a informace o nich nemusí být dostupná formou změn poskytovaných funkcí ``GET /updates``. Změna oprávnění se také může týkat dostupné podoby balíčků. Přidání oprávnění k balíčkům ------------------------------ Přidání oprávnění k sadě balíčků je možné detekovat a reagovat na něj formou zneplatnění, resp. resetování parametru ``nextQuery`` používaného ve funkcí ``GET /updates``. V případě :ref:`digitálního archivu s transakční historií ` je možné do parametru ``nextQuery`` přidat otisk oprávnění. Při žádosti o změny a detekci změny oprávnění je možné poskytnout úplný seznam balíčků od začátku, tj. shodně jako při nezadání parametru ``nextQuery``. Způsob řešení této situace je nutné zvážit v každé jednotlivé implementaci samostatně. Zánik oprávnění k balíčkům ------------------------------ Funkce rozhraní umožňují předávat informaci o zániku balíčku jako takového. Pokud však dojde k situaci, kdy balíček již byl předán z digitálního archivu a druhá strana by s ním neměla dále nakládat, je nutné ji o tomto informovat. Klientské implementace MUSÍ umožnit odstranění takovýchto dříve zpřístupněných balíčků. Tento scénář není podporován v rámci API funkcí. V případě zániku oprávnění ke skupině balíčků je nutné postupovat administrativní cestou.