Open API je standardní definice Web API, pomocí níž je API podrobně popsáno, tj. obsahuje informace o dostupných zdrojích (resources), podporovaných operacích s těmito zdroji atd.
Naleznete v ní mj.:
- definice všech BO a zdrojů
- zdokumentované metody, které je možno na zdrojích použít
- typy chyb, které Web API vrací
- apod.
Endpoint & autentizace
OpenAPI dokumentace je dostupná prostřednictvím endpointu ".../{connection}/api-docs/swagger.json".
Terminologická poznámka: Endpointem se v kontextu API obecně rozumí "konec komunikačního kanálu" (kanálu sloužícího k výměně dat mezi dvěma systémy). V tomto případě se jedná o URL adresu sloužící k získání dokumentace.
K autentizaci je možné použít dvě možnosti:
- buď standardní mechanismus přihlášení pomocí Authorization headeru (viz Autentizace uživatele Web API)
- nebo speciální možnost zavedenou kvůli načítání dokumentace do swagger-ui – query parametr "auth", jehož hodnotou je base64 (přihl. jméno:heslo), jako je tomu v případě Authorization headeru
Řetězec je navíc pro použití v URL adrese zapotřebí zakódovat (URL-encode).
Příklad...
V agendě Uživatelé máme nadefinovaného uživatele s následujícími vlastnostmi:
S použitím libovolného konvertoru volně dostupného na internetu (hledejte "online base64 encode") převedeme přihlašovací řetězec ve formátu jméno:heslo do formátu Base64:
- API:api → QVBJOmFwaQ==
Opět s použitím libovolného online konvertoru převedeme base64 řetězec do formátu vhodného pro použití v URL adrese (hledejte "online url-encode"):
- QVBJOmFwaQ== → QVBJOmFwaQ%3D%3D
Místo dvojice nástrojů můžete použít jediný, pokud podporuje převod do formátu "Base64URL":
- API:api → QVBJOmFwaQ
Dále budeme potřebovat adresu a port, na kterých běží Web API server, a identifikaci spojení.
- server se nastavuje pomocí parametru host v konfiguračním souboru WebAPIServeru (v našem případě předpokládejme localhost)
- portu odpovídá hodnota stejnojmenného parametru port v konfiguračním souboru WebAPIServeru (v našem případě 699)
- identifikaci spojení je alias spojení, jak je deklarován v nástroji DBAdmin.exe (v našem případě data170365)
Z uvedených údajů sestavíme URL, které vložíme do internetového prohlížeče pro získání OpenAPI dokumentaci:
http://localhost:699/data170365/api-docs/swagger.json?auth=QVBJOmFwaQ%3D%3D
Pokud do internetového prohlížeče zadáte URL adresu a nevrátí se nic, častou příčinou jsou nesprávné nebo chybějící autentizační údaje.
Pokud si chceme prohlédnout definici určitého BO, struktury jednotlivých BO (modely) jsou k dispozici pod zdrojem "/{connection}/api-docs/model/{název modelu}", kde "název modelu" je název BO v jednotném čísle, např.: "issuedinvoice". Součástí požadavku opět musí být autentizační údaje.
V našem případě bude URL pro získání struktury BO Faktura vydaná vypadat následovně:
http://localhost:699/data170365/api-docs/model/issuedinvoice?auth=QVBJOmFwaQ%3D%3D
Pokud chcete využívat dokumentaci opakovaně, doporučujeme k jejímu prohlížení využít nástroj Swagger-UI popsaný v následující sekci. (Pomocí nástroje Swagger-UI získáte stejné informace, ale v přehlednější a uživatelsky přívětivější formě.)
Swagger-UI
Swagger-UI je nástroj sloužící k vizualizaci vygenerované dokumentace. Ke stažení je k dispozici např. zde:
git checkout https://github.com/swagger-api/swagger-ui.gitZe staženého balíčku budeme potřebovat obsah podsložky "swagger-ui/dist" (dist obsahuje "zkompilovanou" verzi Swagger-UI).
K provozu aplikace Swagger-UI můžeme využít například PHP built-in server, který spustíme následovně:
php –S localhost:8090PHP built-in server musí běžet na jiném portu, než na kterém poslouchá Web API server (viz parametr port v konfiguračním souboru).
Nechť váš Web API server běží např. na defaultním portu 80. PHP built-in server tedy spustíme např. na portu 8090. Pokud byste měli stažený Swagger-UI uložený např. v cestě C:\API\swagger-ui a PHP webový server v cestě C:\API\php-5.6.25-Win32-VC11-x86\, mohla by dávka pro spuštění aplikace Swagger-UI umístěná v C:\API\ vypadat následovně:
cd swagger-ui\dist
..\..\php-5.6.25-Win32-VC11-x86\php.exe -S localhost:8090PHP server bude po spuštění touto dávkou zobrazovat webový obsah umístěný ve "výchozí" složce, kterou bude C:\API\swagger-ui\dist:
Listening on http://localhost:8090
Document root is C:\API\swagger-ui\dist
Press Ctrl-C to quit.
Následně je třeba ve webovém prohlížeči přejít na adresu s obsahem, který webový server zobrazuje. Tj. zadat do webového prohlížeče adresu s příslušným portem:
localhost:8090
Poté, co server vrátí odpověď, do adresního řádku (nahoře) zadat adresu endpointu vč. URL zakódovaných "auth" údajů, jak bylo řečeno výše. Tj. např.:
http://localhost/data/api-docs/swagger.json?auth=U3VwZXJ2aXNvcjo%3D
Pokud máte Web API server nakonfigurovaný na jiný port než defaultní 80 (viz parametr port v konfiguračním souboru), je zapotřebí tento port uvést i v adrese pro získání dokumentace. Tj. např. v případě portu 81:
http://localhost:81/data/api-docs/swagger.json?auth=U3VwZXJ2aXNvcjo%3DStanou se 2 věci:
- Za cca 20s se vygeneruje definice (při dalších dotazech je cachovaná, takže je vracena instantně po dobu cca 15 minut nebo restartu aplikačního serveru)
- Prohlížeč bude výslednou definici v závislosti na použitém hardware cca 2 minuty zpracovávat
Po vygenerování jsou zobrazeny všechny endpointy, ke každému z nich je k dispozici model vraceného/přijímaného objektu a popis. Zde si můžete např. dohledat, pod jakým zdrojem je k dispozici faktura vydaná apod.:
Můžete si zobrazit datový model, typy chyb na daném BO apod.:
Pokud by vyvstala potřeba prohlédnout si definici BO napřímo (tj. JSON), tak struktury jednotlivých BO (modely) jsou k dispozici pod zdrojem "/{connection}/api-docs/model/{název modelu}", kde "název modelu" je název BO v jednotném čísle, např.: "issuedinvoice". (Pozor, při dotazování nezapomenout na autentizaci.)
U modelů jsou v popisech fieldů BO záměrně označeny persistentní položky, jelikož ty jsou ve výchozím stavu vraceny při dotazech na kolekce BO.
Uživatelsky definovatelné položky ve výchozích dotazech na kolekce BO vraceny nejsou.
Pro používání OpenAPI je prozatím zapotřebí mít spuštěný aplikační server. (Tj. mít v nexus.cfg v části [Client] nastaveno Local na hodnotu 0.)