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 umožní registráciu domén. Počet domén nie je obmedzený a služba sa aktivuje a platí individuálne za každú doménu.

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 do API rozhrania na serveri bizdata.sk. Nájdete ho po prihlásení v časti Nastavenia účtu. API kľúč nikomu neposkytujte a pri podozrení na zneužitie ihneď vygenerujte nový a vymeňte ho na všetkých integrovaných doménach. Viac o autentifikačných kľúčoch..

3. Vloženie scriptu na web

Keď zistíte svoj API kľúč, môžete previesť samotnú integráciu vložením scriptu na Vašom webe resp. do online 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.

Pri prvej úspešnej požiadavke bude doména, z ktorej script odosiela požiadavku na bizdata.sk, automaticky zaregistrovaná (pokiaľ je v nastaveniach účtu povolené "Automaticky registrovať novú doménu") a priradená ku zistenému užívateľskému účtu. Súčasne bude majiteľovi domény odoslaný email o zaregistrovaní novej domény. Tým je integrácia prevedená a ku doméne sa začnú evidovať logy a štatistiky - napr. počty zostávajúcich požiadaviek, autorizované požiadavky atď.

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 povolených 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 vyriešenie poskytuje aplikácia bizdata.sk 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, bude môžete nás kontaktovať s popisom chyby, prípadne priložiť obrázok s chybou a uviesť Váš prihlasovací email a názov problematickej domény.

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 prevádzkovateľa službu, alebo až zablokobvaniu účtu či domény - 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ť 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 obsiahla a obsahuje niekoľko desiatok gigabajtov dát. Ich stiahnutie 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 - veľmi rýchlo by sa vyčerpal limit povolených API požiadaviek. V praxi sa preto nastavuje mierne oneskorenie a požiadavka sa odošle až po uplynutí napr. 0.5 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.

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.