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.