.. _api_v2_news: ========================= Novinky a změny API v2 ========================= API verze 2 vychází z původního :ref:`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. .. _api_v2_news_rest: 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 :ref:`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``. .. _api_v2_news_schema: 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 :ref:`api_v2_changes_batch_users`. Zpráva o chybě při zpracování dávky byla přepracována a původní element ```` (komplexní typ ``BatchUpdateError`` v XML schématu) byl nahrazen novým elementem ```` (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 :ref:`api_v2_issues`. 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.