API Integrácia - Postup

1. Bezplatná registrácia - vytvorenie užívateľského účtu

Pre vytvorenie užívateľského účtu je potrebné zaregistrovať svoj platný email, na ktorý budú odoslané prístupové údaje. Po prvom prihlásení sa účet aktivuje a je možné registrovať webové domény, resp. aplikácie na účel API integrácie. Počet registrovaných domén nie je obmedzený, pričom každý web, resp. aplikácia sa aktivuje a platí individuálne.

2. Vyhľadanie API kľúča

API kľúč je jedinečný identifikátor užívateľského účtu a je potrebné ho odoslať spolu s každou požiadavkou na API rozhranie na serveri bizdata.sk. Nájdete ho po prihlásení v časti API Integrácia. API kľúč nikomu neposkytujte a pri podozrení na zneužitie vygenerujte nový a vymeňte ho na všetkých integrovaných weboch a aplikáciách.

3. Vloženie scriptu na web alebo do aplikácie

Po zistení API kľúča môžete previesť samotnú integráciu vložením scriptu na Vašom webe resp. do aplikácie. Je potrebné rozhodnúť akým spôsobom bude integrácia prevedená - prostredníctvom javascript jQuery, javascript vanilla scriptu, alebo na strane servera odoslaním REST požiadavky. Odporúčame prezrieť si vzorové implementácie, ktoré uľahčia rozhodnutie s ohľadom na obtiažnosť a dostupné knižnice.

4. Optimizácia nastavení

Po úspešnom načítaní a zobrazení zoznamu subjektov odporúčame optimizovať nastavenia tak, aby nedochádzalo ku zbytočnému, alebo príliš rýchlemu vyčerpaniu limitu požiadaviek. Napríklad pri použití javascript knižníc je vhodné nastaviť oneskorené odoslanie požiadavky medzi dvoma stlačeniami klávesov - tzv. throttling (tzn. zoznam subjektov sa načíta až po uplynutí napr. 0.5 sekundy od posledného stlačenia klávesy). Pozrite nižšie "Dobré praktiky".

5. Testovanie a riešenie problémov

V procese integrácie môže nastať mnoho chybových stavov. Pre ich riešenie možno využiť niekoľko nástrojov. Najjednoduchšie je preverenie logových záznamov pod užívateľským účtom, kde sa zaznamenávajú príčiny zamietnutia požiadavky - napr. vyčerpanie povoleného limitu, nesprávny parameter apod.

Pokiaľ nie je v logových záznamoch žiadna informácia, môže byť vhodné využiť niektorú podpornú API metódu a preveriť dostupnosť API rozhrania, alebo platnosť API kľúča. Pokiaľ ani to nepomôže, môžete nás kontaktovať s popisom chyby, uvedením názvu problematickej aplikácie / webu, príp. priložiť obrázok s chybou.

Z dôvodu zabezpečenia stability služby sú určité postupy zakázané a ich opakované porušovanie môže viesť ku napomenutiu zo strany poskytovateľa, príp. až zablokovaniu užívateľského účtu alebo problematického webu - napríklad:

Úmyselné preťažovanie servera

Ak užívateľ opakovane odošle veľký počet požiadaviek v krátkom čase, jedná sa o úmyselné preťažovanie servera. Server samozrejme nie je počas štandardnej prevádzky nastavený na nárazovú krátkodobú záťaž a môže sa správať nepredvídateľne. Môže napríklad nastať dočasný výpadok služby, čo ovplyvní aj iných užívateľov. Prevádzkovateľ služby môže v takom prípade požiadať užívateľa o vysvetlenie, korekciu implementácie, alebo zablokovať požiadavky z problematickej domény príp. aj užívateľský účet.

Sťahovanie údajov

Nie je dovolené systematicky sťahovať údaje o subjektoch za účelom vytvorenia kópie databázy. Jednak by došlo ku rýchlemu vyčerpaniu povoleného limitu požiadaviek a jednak je to proti obchodným podmienkam prevádzkovateľa služby. Databáza subjektov je skutočne veľká a obsahuje niekoľko desiatok gigabajtov dát. Stiahnutie všetkých záznamov bežným spôsobom je takmer nemožné, resp. v praxi by mohlo trvať niekoľko týždňov. Kontaktujte nás, ak potrebujete získať kompletnú databázu subjektov.

Throttling

Tzv. "throttling" zabezpečí mierne oneskorenie odoslania požiadavky z javascriptov. Pri písaní hľadaného slova je vhodné začať vyhľadávanie až po jeho napísaní. Bolo by zbytočné hľadať slovo pri každom stlačení klávesy, nakoľko by sa veľmi rýchlo vyčerpal povolený limit API požiadaviek. V praxi sa preto nastavuje mierne oneskorenie a požiadavka sa odošle až po uplynutí napr. 0.5 - 0.7 sekundy od posledného stlačenia klávesy. Užívateľ si nevšimne žiadny rozdiel a Vy ušetríte niekoľko zbytočne odoslaných požiadaviek.

Pri použití predpripravených knižníc podľa dokumentácie je už throttling štandardne nastavený, pri využití serverovej integrácie alebo vlastných knižníc je potrebné toto nastavenie zohľadniť v procese implementácie.

Caching

Odporúčame napríklad implementovať cachovanie vrátených odpovedí, nakoľko užívatelia majú tendenciu opakovane vypĺňať rovnaké subjekty. Cachovanie vrátených požiadaviek môže ušetriť približne 10-20% požiadaviek.