.. _api_intro:

=================
Seznámení s API
=================

API systému CAM je tvořeno sadou REST rozhraní. Přes tato rozhraní
jsou data obvykle zasílána ve formátu XML. Význam přenášených dat a
jejich vnitřní struktura je popsána v části :ref:`ont`.

Entita je tvořena identifikátory a prvky popisu uspořádaných do částí.

Identifikátory entity
===========================

Každá entita v systému má dva jednoznačné identifikátory. 
Primárním identifikátorem je číslo entity. Sekundárním
identifikátorem je UUID entity. Oba identifikátory jsou
pevné a nelze je v rámci životního cyklu entity měnit.

Identifikátor UUID lze předat z vnějšího systému již
v okamžiku zakládání nové entity. Předání hodnoty identifikátoru
umožňuje zajistit vazbu mezi novou entitou a její reprezentací
v dalších systémech, resp. vazbu mezi zdrojovým systémem 
a CAMem. Výhodou je, že vazba mezi zdrojovým systémem a 
CAMem nemusí být přímá, současně zabraňuje vzniku duplicit.
Pokud UUID není předáno společně s vkládanou entitou, je
automatizovaně při uložení vygenerováno.


Struktura entity
===========================

Struktura přístupového bodu je pevná a skládá se z těchto částí:

 - jednotlivá označení přístupového bodu, z nichž 
   jedno tvoří preferované označení.
 - další identifikátory (například IČ, kód RÚIAN)
 - informacemi o vzniku, či zániku přístupového
 - komplexní události a vztahy popisující přístupový bod
   (například informace o studiu u osoby)
 - popisné prvky (například historie, genealogie)

Každý z výše uvedených bodů tvoří samostatnou oblast popisu 
entity. Takováto oblast je popsána pomocí prvků popisu.
Metodika pro popis entit definuje,
kdy lze daný prvek popisu použít a způsob jeho užití.