IdH 2 REST API: Dokumentace requestu pro získání identifikátoru

getPhysDocReport

Request getPhysDocReport je hlavní a nejdůležitější request, který zjistí úplnou informaci o fyzickém exempláři, včetně jeho registrovaného identifikátoru (pokud v systému existuje), informace o známých digitalizátech a úplnou historii dokumentu (konkordance).

O tuto informaci si lze říci různými způsoby:

• Pro získání jednoznačné Tier 0 odpovědi:
  • pomocí physId,
  • pomocí úplné a přesné 4D lokační informace (obsahuje kompletní lokační informace a čas jejich platnosti).
• Pro získání výsledku hledání (Tier 1+ odpovědi):
  • pomocí neúplné 4D lokace (například s neúplnou lokační informací a nutným fulltextovým hledáním),
  • pomocí úplné nebo neúplné 3D lokace (bez uvedení času její platnosti).

Parametry

• physId: registrovaný identifikátor fyzického exempláře - pokud znám registrovaný identifikátor fyzického exempláře, mohu jej použít pro získání kontrolního kódu fyzického exempláře;
• shelfmark: signatura fyzického exempláře;
• locName: název místa uložení (např. název instituce);
• locPlace: místo (obec) uložení fyzického exempláře;
• when: doba platnosti lokační informace / signatury (více o využití parametru when v praxi zde);
• maxTier: jaký Tier odpovědi má odpověď obsahovat; parametrem je celé číslo v rozsahu [0..2]; defaultně 2 (kompletní informace); pomocí tohoto parametru mohu vyloučit z odpovědi nejednoznačné informace

Typy requestů

Odpověď

Odpověď obsahuje:

• error: indikuje úspěšnost vyřízení requestu
  • code: kód chyby; 0 = vše OK;
  • msg: slovní vyjádření chyby; OK = vše OK
• result: obsahuje odpovědi organizované podle přesnosti a jednoznačnosti
  • tier0: obsahuje jednoznačnou odpověď na jednoznačné a úplné dotazy; nastává tehdy, když v systému jsou data, která umožňují poskytnout jednoznačnou odpověď (drtivá většina situací); obsahuje pole o velikosti jednoho prvku s informacemi o odpovídajícím exempláři
  • tier1: obsahuje nejednoznačnou odpověď na jednoznačné a úplné dotazy; nastává tehdy, když v systému jsou data, která neumožňují poskytnout jednoznačnou odpověď ani v případě jednoznačného a úplného dotazu - například pokud v minulosti došlo k excesům typu referencování více dokumentů v jednom místě uložení se stejnou signaturou (teoreticky velmi vzácné situace); obsahuje pole s informacemi o odpovídajících exemplářích
  • tier2: obsahuje nejednoznačnou odpověď na nejednoznačné či neúplné dotazy; nastává tehdy, když dotaz má charakter hledání a systém tedy vrací informace, které by mohly odpovídat dotazu (například při zadání neúplného placeName, neúplné signatury apod.); obsahuje pole s informacemi o odpovídajících exemplářích
• request: zopakovaný název requestu

Systém se snaží naplnit tier0, tier1 a tier2, pokud není tato snaha omezena použitím parametru maxTier v requestu, a je na partnerském systému, jak informace v tier2 využije ve prospěch vlastních uživatelů (nabízení alternativ typu "možná se snažíte najít tento dokument?").

Struktura tier0, tier1 a tier2 property je shodná, jednotlivé prvky pole obsahují:

• physId: platný identifikátor fyzického exempláře
• locCode: aktuální kontrolní kód lokace exempláře
• concordanceEvents: kompletní systému známá historie událostí souvisejících s umístěním exempláře (ať už se události týkaly přesunu exempláře, změn celého místa uložení (instituce) nebo jiných specifických události (zánik, svázání do konvolutu apod.)

Struktura concordanceEvents:

• from: datum, od kterého daný stav trval ve formátu W3C
• to:  datum, do kdy daný stav trval ve formátu W3C nebo jako NOW pro indikaci, že stále trvá
• physId: identifikátor fyzického exempláře (typicky je shodný s result.physId, ale nemusí být, pokud v životním cyklu dokumentu došlo například k rozešití konvolutu - čili vzniku jiného exempláře - apod.)
• locCode: kód lokace exempláře
• shelfmark: signatura platná v době platnosti konkordančního záznamu,
• locId: identifikátor místa uložení
• locName: formální a správný název instituce / místa uložení
• locPlace: název místa (obce) uložení