3.2. Novinky a změny API v2

API verze 2 vychází z původního API verze 1 a rozšiřuje jej o nové možnosti a zpřesňuje některé existující. Novinky a změny v API verze 2 jsou popsány v této kapitole.

3.2.1. REST služby

REST služby jsou dostupné na URL /api/v2.

Služby, které mohou trvat delší dobu byly přepracovány na asynchronní volání. U těchto volání je možné zjistit stav zpracování a následně získat výsledek. Současně došlo k upřesnění chybových stavů a byla přidána definice strukturované výjimky pro zpracování chybových stavů.

V rámci definice typů v definici OpenAPI byly zavedeny nové typy: EntityId, Uuid, EntityRef, TransactionId, ExportRequestId.

Operace GET /entities/{id}

  • vstupem je je číslo nebo uuid (dříve byl řetězec)

  • definován nový návratový kód EntityNotFound

Operace POST /export/snapshots

  • upraveny vstupní parametry jako pole čísel nebo uuid (dříve pole string)

  • metoda je nově asynchronní, vrací se pouze informace o zahájení operace

Operace POST /export/revisions

  • upraveny vstupní parametry jako pole čísel nebo uuid (dříve pole string)

  • metoda je nově asynchronní, vrací se pouze informace o zahájení operace

Vyhledávání POST /search

  • struktura QueryParamsDef: odstraněno pole codes, vyhledávání v definované skupině entit pomocí ID se nepoužívá

  • navíc možnost vyhledávání dle userRole a user

  • limit na velikost stránky je 1000

Získání změn v entitách GET /updates?fromTransId={fromTransId}&toTransId={toTransId}

  • limit na velikost stránky je 50000

Zaslání změnové dávky POST /batches

  • metoda je nově asynchronní, vrací se pouze informace o zahájení operace

  • pro ověření stavu zpracování změnové dávky se použije GET /batches/{updateRequestId}/status

  • pro získání výsledku zpracování změnové dávky se použije GET /batches/{updateRequestId}/result

Ověřování změnové dávky

Nová operace pro zaslání testovací změnové dávky POST /batches/test.

3.2.2. Schéma XML

Princip schématu dat a změnových dávek je verzi 2 zachován shodně s verzí 1. Došlo k úpravě názvů elementů a atributů, které byly zpřesněny a rozšířeny pro snazší lidskou čitelnost z původních zkratek na délku slov. Například: id -> entityId, prts -> parst, či bu -> batchUpdate. Vlastní názvy typů, kde to bylo možné, v XML schématu zůstávají zachovány.

Zcela přepracován je mechanismus předávání informací o uživatelích a jejich rolích ve vztahu k entitě. Podrobněji viz Uživatelé.

Zpráva o chybě při zpracování dávky byla přepracována a původní element <bue> (komplexní typ BatchUpdateError v XML schématu) byl nahrazen novým elementem <batchUpdateFailure> (komplexní typ BatchUpdateFailure v XML schématu). Nová podoba záznamu obsahuje podrobný popis jednotlivých chyb a upozornění. Práce s upozorněními a chybami je podrobněji popsána v kapitole Zjištění (chyby a upozornění).

Součástí informace o verzi entity a jejích změnách je nově verze metadat. Ta je významná pro systémy, které budou pracovat s jednotlivými upozorněními. Pokud systém nemění a nepřidává jednotlivá upozornění, tak je možné metadatové verze entity ignorovat.