1.2. Endpointy pro přístup k editačním webovým službám
API editačních služeb je dostupné protokolem HTTPS. Komunikace probíhá v režimu „request-response“ ve formátu XML (nikoli však SOAP). Aplikace zasílá POST „request“ s požadovanou metodou na příslušný endpoint editační služby, služba pak odpovídá pomocí „response“, anebo v případě neúspěchu „error response“. Zaslané požadavky musejí být autentizovány.
Verze 1.1 webových služeb se od verze 1.0 liší rozdílným jmenným prostorem XML, způsobem autentizace (mTLS oproti basic HTTP authentication) a adresou endpointů.
1.2.1. Endpointy pro přístup k WS 1.0
Prostředí |
Adresa |
|---|---|
integrační |
https://externaleditapi10.caais-test-ext.gov.cz/spravadat/ws/call/exampleId |
školicí |
https://externaleditapi10.caais-edu.gov.cz/spravadat/ws/call/exampleId |
produkční |
https://externaleditapi10.caais.gov.cz/spravadat/ws/call/exampleId |
Pokud jste připojeni do CMS, použijete místo domény gov.cz doménu cms2.cz.
Hodnota parametru exampleId obsahuje zkratku subjektu z CAAIS.
Formát URL
Na rozdíl od endpointů JIP/KAAS nekončí endpointy CAAIS lomítkem.
1.2.1.1. Nastavení subjektu v CAAIS
Subjekt musí mít dovoleno použití aplikačního rozhraní – záložka Ostatní na detailu subjektu v CAAIS GUI, jinak volání služby selže.
1.2.1.2. Autentizace
Aplikace třetí strany musí službu volat s basic HTTP authentication, tzn. zadáním uživatelského jména a hesla lokálního administrátora [1]. Systém CAAIS pak aplikaci třetí strany povolí přístup dle definovaných přístupových práv k danému subjektu. Pro zabezpečení komunikace je dovoleno používat pouze šifrování protokolem TLS 1.2 nebo TLS 1.3, ostatní verze (SSL, TLS 1.0, TLS 1.1) nejsou povoleny.
Příklad volání endpointu
#!/bin/zsh
endpoint='https://externaleditapi10.caais-test-ext.gov.cz/spravadat/ws/call/DIACZ'
username='local_admin'
password='secret_password'
curl -i \
-u $username:$password --basic \
-H 'Content-Type: text/xml' \
--data-raw '<GetVersionRequest xmlns="http://userportal.novell.com/ws/WS-LA-1.0"/>' \
$endpoint
1.2.2. Endpointy pro přístup k WS 1.1
Podle kategorie volané metody je nutné zvolit jeden ze tří endpointů.
1.2.2.1. Kategorie metod editačních služeb
Každou metodu editační služby je nutné volat na správném endpointu podle kategorie, do které spadá:
ws-edit/1 – čtení a zápis údajů daného subjektu (odpovídá webové službě verze 1.0)
čtení a správa dat vlastního subjektu
čtení a správa dat podřízených subjektů, které přenesly působnost lokálního administrátora na daný subjekt
ws-edit/2 – specializované metody pro daný subjekt
ztotožnění osoby v ROB (přiřazení AIFO k uživateli)
načtení seznamu podřízených subjektů, které přenesly působnost lokálního administrátora nebo čtení dat subjektu na daný subjekt
načtení historie změn dat za definované období
ws-edit/3 – čtení dat pro daný subjekt (odpovídající read-only metodám ws-edit/1)
čtení dat vlastního subjektu
čtení dat podřízených subjektů, které přenesly působnost čtení dat subjektu na daný subjekt
Pokud jste připojeni do CMS, použijete místo domény gov.cz doménu cms2.cz.
Hodnota parametru exampleId obsahuje zkratku subjektu z CAAIS.
Formát URL
Na rozdíl od endpointů JIP/KAAS nekončí endpointy CAAIS lomítkem.
1.2.2.2. Nastavení subjektu v CAAIS
Subjekt musí mít dovoleno použití aplikačního rozhraní – záložka Ostatní na detailu subjektu v CAAIS GUI, jinak volání služeb selže.
1.2.2.3. Autentizace
Aplikace třetí strany musí službu volat s mTLS autentizací, tzn. s použitím klientského x509 certifikátu [2]. Certifikát je nutné nejprve registrovat v CAAIS pod konfigurací libovolného AIS pod daným subjektem [3]. Certifikát musí být vydán podporovanou certifikační autoritou. Pro zabezpečení komunikace je dovoleno používat pouze šifrování protokolem TLS 1.2 nebo TLS 1.3, ostatní verze (SSL, TLS 1.0, TLS 1.1) nejsou povoleny.
Příklad volání endpointu
#!/bin/zsh
endpoint='https://cert-externaleditapi11.caais-test-ext.gov.cz/spravadat/ws-edit/1/call/DIACZ'
curl -i \
--key idm.key --cert idm.crt \
-H 'Content-Type: text/xml' \
--data-raw '<GetVersionRequest xmlns="http://userportal.novell.com/ws/WS-LA-1.1"/>' \
$endpoint