Hommikul avad e-poe halduspaneeli, tarnepartneri keskkonna ja Exceli. Kopeerid tellimused ühest süsteemist teise, uuendad laoseisu, kontrollid saadetise andmeid ning saadad kliendile kinnituse. Töö kordub iga päev, võtab aega ja isegi hoolika tegutsemise korral võib mõni tootekood, kogus või aadress valesse kohta sattuda.
API liidestamine aitab sellise töövoo ümber ehitada nii, et süsteemid vahetavad infot omavahel. Inimene ei pea enam iga sammu käsitsi käivitama, vaid saab keskenduda eranditele, kliendisuhtlusele ja ärilistele otsustele. Allpool vaatame rahulikult, mida API endast kujutab, millal ühendus end ära tasub, kuidas projekt tehniliselt läbi viiakse ning millal tasub appi võtta arenduspartner.
Sisukord
- Mis on API liidestamine ja miks see äri jaoks oluline on
- Millal API liidestamine ära tasub ja millal mitte
- API liidestamise tehniline töövoog
- Turbe ja jõudluse põhimõtted
- Näited ja juhtumiuuringud Eesti ettevõtetest
- Ise ehitada, valmislahendus või partner
- Kokkuvõte ja järgmised sammud
Mis on API liidestamine ja miks see äri jaoks oluline on
API tähendab rakenduse programmeerimisliidest. Lihtsamalt öeldes on see kokkulepitud viis, mille kaudu üks tarkvara küsib teiselt andmeid või palub sellel tegevuse käivitada. API integratsioon ehk API-liidestus ühendab need süsteemid nii, et info liigub nende vahel kindlate reeglite järgi.
Hea analoogia on restoran. Üks programm töötab nagu köök, teine nagu saal. Klient esitab tellimuse saalis, köök valmistab toidu ja kelner viib info nende kahe vahel. API ongi selles näites kelner. Ta teab, millises vormis tellimus vastu võtta, kuhu see viia ja milline vastus tagasi tuua. Ta ei otsusta ise menüü üle, vaid järgib süsteemide vahel kokku lepitud liidest.
E-poe puhul võib klient teha tellimuse veebis, mille järel liiguvad tellimuse andmed majandustarkvarasse, laohaldusse või tarnepartnerile. Vastuseks võib e-pood saada tellimuse kinnituse, jälgimisnumbri või saadetise staatuse. Oluline on, et inimene ei pea iga vaheetappi käsitsi kopeerima.
Kolm ärilist võitu
- Aeg: töötajad ei kuluta tööpäeva korduvatele kopeerimis- ja kontrollitoimingutele.
- Vähem vigu: süsteem kasutab iga kord sama loogikat, vähendades käsitsi sisestamisest tulenevaid eksimusi.
- Skaleeruvus: kui tellimuste, toodete või klientide hulk kasvab, ei pea iga uue töömahu jaoks samas tempos inimesi juurde lisama.
API-liidestamine pole siiski lihtsalt nupp, mis kaks tarkvara kokku ühendab. Enne arendust tuleb otsustada, milline süsteem on konkreetse info allikas, millal andmed liiguvad, mida teha puuduvate väljadega ja kuidas käituda katkestuse korral. Kui need reeglid jäävad kokku leppimata, võib automaatne ühendus küll töötada, kuid viia vale info kiiresti mitmesse süsteemi.
Praktiline reegel: automaatika ei paranda ebaselget protsessi. Kõigepealt lepi kokku, milline andmevoog peab toimima, seejärel vali tehniline lahendus.
Millal API liidestamine ära tasub ja millal mitte
API-liidestus annab kõige rohkem väärtust siis, kui see eemaldab korduva ja äriliselt olulise käsitöö. Esimene märk on see, et sama infot kopeerivad iga päev mitu töötajat. Teine on vajadus hoida kaks süsteemi pidevalt sünkroonis, näiteks e-pood ja ladu. Kolmas tekib kasvufaasis, kui tellimuste või toodete hulk suureneb ning olemasolev käsitöö muutub aeglaseks ja ebakindlaks.
Eesti avalik sektor annab hea tausta. RIA kirjeldab X-teed turvalise andmevahetuskihina, mis tähendab, et süsteemide ühendamisel tuleb arvestada mitte ainult tehnilise lõpp-punktiga, vaid ka teenuste avaldamise, autentimise ja masin-masin suhtluse korraldusega. See on kasulik õppetund ka eraettevõttele, eriti juhul, kui liidestus puudutab tundlikke andmeid või reguleeritud valdkonda.
Sarnane põhimõte toimib Statistikaameti puhul. Statistikaameti arendajatele mõeldud juhend kirjeldab andmebaasi API-t aadressil andmed.stat.ee, SDMX-i XML- ja JSON-vormingut ning võimalust pärida nii andmetabeleid kui ka struktuurikirjeldusi. Varasemalt kasutatud andmebaas.stat.ee suunati uuele PxWebi lahendusele 2021. aasta esimeses pooles. Ettevõtte jaoks näitab see, kuidas avalikud andmed võivad olla masinloetavalt kasutatavad, mitte ainult käsitsi allalaaditavad.
Millal oodata
Liidestus on põhjendatud, kui:
- Andmed korduvad: sama tellimuse, kliendi või tooteinfo sisestamine toimub eri süsteemides.
- Sünkroonsus loeb: laoseis, hind, saadavus või tellimuse staatus peab jõudma teise süsteemi kiiresti.
- Protsess kasvab: praegune töökorraldus toimib väikese mahu juures, kuid tekitab suurema koormuse korral viivitusi ja vigu.
Millal oodata
Iga andmevahetus ei vaja eriarendust. Ühekordse ülekande puhul võib käsitsi kontrollitud import olla mõistlikum. Sama kehtib väikese andmemahu korral või siis, kui kasutatav platvorm pakub juba sobivat pistikprogrammi või valmisühendust.
Meeskonnaga tasub arutada üht konkreetset küsimust: milline korduv tegevus tekitab praegu kõige rohkem ajakulu või riski ning kas selle automatiseerimine muudaks igapäevatööd mõõdetavalt lihtsamaks? Kui vastus jääb ebamääraseks, pole tehniline lahendus veel piisavalt täpselt sõnastatud.
API liidestamise tehniline töövoog
Hea API-projekt algab äriprotsessist, mitte koodist. Arendaja peab aru saama, milline tegevus käivitab andmevahetuse, milline süsteem omab algandmeid ja mida peab teine süsteem vastuseks tegema. Sama loogika kehtib nii WordPressi API kui ka ERP-i ühenduse puhul.
Esimene etapp on disain
Pane esmalt kirja andmevoog. Näiteks klient esitab e-poes tellimuse, e-pood saadab tellimuse majandustarkvarasse, majandustarkvara annab vastu dokumendi tunnuse ja laosüsteem tagastab saadavuse.
Lihtne skeem aitab varakult märgata küsimusi, mida ekraanilt vaadates ei näe:
- millised andmed liiguvad;
- kummast süsteemist need algavad;
- kas liikumine toimub sündmuse, ajastatud päringu või kasutaja tegevuse järel;
- mis juhtub siis, kui sihtsüsteem ei vasta.
Teine etapp on autentimine
Ühendus peab suutma tõendada, et päring tuleb õigest rakendusest. Selleks võib teenusepakkuja kasutada API-võtit, OAuth 2.0 lahendust või X-tee puhul turvaserverit ja seotud teenuseavaldamise loogikat.
Siin ei piisa sellest, et ühendus töötab arendaja arvutis. Tuleb määrata, milline rakendus tohib andmeid lugeda, milline tohib neid muuta ning kus hoitakse ligipääsutunnuseid. Õigused peaksid vastama tegelikule vajadusele, mitte olema võimalikult laiad.
Kolmas etapp on andmemudelite sobitamine
Kaks süsteemi võivad rääkida samast asjast erinevate nimedega. Ühes süsteemis võib toote tunnus olla product_code, teises sku. Üks süsteem võib kasutada kuupäeva ja kellaaega, teine ainult kuupäeva. Arendus peab need erinevused teadlikult kokku viima.
JSON ja XML on levinud andmevormingud, kuid vorming ise ei lahenda sisulist vastendamist. Lepi kokku, millised väljad on kohustuslikud, millised vabatahtlikud ning mida teha siis, kui väärtus puudub või ei vasta oodatud kujule.
Neljas etapp on vigade käitlemine
API võib olla ajutiselt kättesaamatu, vastus võib sisaldada veateadet või mõni vajalik väli võib puududa. Süsteem peab sellises olukorras käituma ette määratud viisil.
Praktiline lahendus võib sisaldada uuesti proovimist, päringu aegumist, järjekorda ja logikirjet. Uuesti proovimine peab olema kontrollitud, sest sama tellimuse korduv saatmine võib tekitada dubleeritud dokumendi. Seetõttu tuleb eristada ajutist ühendusviga sisulisest veast, mida automaatne kordus ei paranda.
Viies etapp on testimine
Testi ühendust eraldi test- või arenduskeskkonnas. Kontrolli nii tavapärast õnnestunud voogu kui ka puuduvat aadressi, tundmatut tootekoodi, topelttellimust ja katkestatud ühendust.
Koormustest aitab näha, kuidas lahendus reageerib siis, kui päringuid tuleb lühikese aja jooksul rohkem. Testimise eesmärk pole ainult kontrollida, kas andmed jõuavad kohale, vaid ka seda, kas need jõuavad õigesse kohta õiges vormis.
Kuues etapp on monitooring
Lansseerimine ei tähenda projekti lõppu. Pärast kasutuselevõttu peab meeskond nägema, kas päringud õnnestuvad, kui kaua vastused aega võtavad ja millised vead korduvad.
Seire võib saata teavituse, kui ühendus katkeb, vigade hulk kasvab või järjekorda jääb töötlemata sõnumeid. Dokumentatsiooni, arenduse ja tehnilise projektijuhtimise saab siduda vDisaini tarkvaraarenduse teenusega, kui ettevõttel pole kogu vajalikku kompetentsi majas olemas.
Turbe ja jõudluse põhimõtted
API-liidestuse turve ja jõudlus tasub enne lansseerimist kontroll-lehele panna. Nii ei jää olulised küsimused ainult arendaja või projektijuhi mällu.
Turbe kontrollnimekiri
- Autentimine: halda OAuth 2.0 luba ja API-võtmeid turvaliselt, piira nende kasutusõigusi ning vaheta need kontrollitud korras.
- Krüpteeritud liiklus: kasuta HTTPS-i, et andmed liiguksid süsteemide vahel kaitstud ühenduse kaudu.
- Vähim vajalik info: saada ainult neid andmeid, mida konkreetne tegevus vajab. Väldi liigsete isikuandmete kopeerimist teise süsteemi.
- Logide varjestamine: ära kirjuta logidesse paroole, võtmeid ega tundlikku kliendiinfot.
- Isikuandmed: määra, kes tohib andmeid näha, kui kaua neid säilitatakse ja kuidas töötlemine vastab GDPR-i nõuetele.
Jõudluse kontrollnimekiri
Päringute piiramine ehk rate limiting kaitseb teenust olukorras, kus üks klient saadab liiga palju päringuid. Vahemälu aitab korduvatele küsimustele kiiremini vastata, päringute koondamine vähendab asjatut suhtlust ning aegumised ja retries-strateegiad hoiavad süsteemi kontrolli all ka ajutise tõrke korral.
Monitooringus jälgi vähemalt latentsust, veaprotsenti ja süsteemi tervisekontrolli tulemust. Kui ühendus annab kasutajale küll vastuse, kuid teeb seda liiga aeglaselt, on tegemist jõudlusprobleemiga. Kui logisid kogutakse, kuid keegi neid ei vaata, pole seire veel tööprotsessi osa.
Näited ja juhtumiuuringud Eesti ettevõtetest
API-liidestuse väärtus muutub selgemaks siis, kui vaadata tervet töövoogu, mitte ainult üht tehnilist päringut. Järgmised näited kirjeldavad realistlikke olukordi, millega Eesti e-kaubanduses ja laohalduses kokku puututakse.
Keskmise suurusega WooCommerce'i e-pood võib ühendada oma tellimused tarnepartneri API-ga. Pärast ostu liiguvad tellimuse number, saaja andmed ja saadetise sisu partnerile. Kui pakk on vastu võetud või välja saadetud, jõuavad jälgimisnumber ja staatus tagasi e-poodi, kus klient näeb uut infot ning ettevõte ei pea seda käsitsi sisestama.
Õppetund on identifikaatorite valik. Kui e-pood kasutab tootel oma tunnust, aga tarnepartner tunneb toodet teise koodi järgi, peab süsteem nende vahelise vastendamise teadlikult säilitama. Vastasel korral võib tellimus küll tehniliselt liikuda, kuid sisaldada vale toodet või jääda töötlemata.
Teises olukorras liiguvad ERP-i ja e-poe vahel laoseisud, hinnad ja tootekaardid. ERP võib olla toodete põhiandmete allikas, e-pood aga müügi- ja kliendikanal. Kui toode muutub laos kättesaamatuks, peab e-pood saama selle info kätte vastavalt kokkulepitud reeglile, mitte juhusliku käsitsi uuenduse kaudu.
vDisaini projektikogemusest lähtuv praktiline tähelepanek on, et kõige rohkem tööd ei nõua alati ühenduse loomine, vaid andmete korrastamine ja erinevate süsteemide loogika kokkusobitamine. Directo API liidestuse lahenduste juures tulebki arvestada, kuidas olemasolev äriprotsess, tellimused ja majandustarkvara omavahel kokku sobivad.
Teine korduv õppetund puudutab veaooteaega. Kui ettevõte eeldab, et iga päring saab vastuse kohe, kuid partneri süsteem töötab viivitusega, võib e-pood näidata kliendile ekslikku saadavust. Seetõttu tuleb kokku leppida, kas kasutaja ootab vastust, kas andmed lähevad järjekorda või kuvatakse ajutine staatus.
Ise ehitada, valmislahendus või partner
Kolme tee vahel valides vaata korraga keerukust, andmete tundlikkust, meeskonna oskusi, ajakulu ja kogukulu. Kõige odavam algus pole alati kõige soodsam lahendus, kui hilisem hooldus, veaparandus ja platvormimuudatused jäävad arvestamata.
| Kriteerium | Ise ehitada | Valmislahendus | Partner |
|---|---|---|---|
| Projekti keerukus | Sobib selge ja piiratud ulatusega ühendusele | Sobib tavapärasele kasutusjuhule | Sobib mitme süsteemi ja eriloogikaga projektile |
| Sisemine meeskond | Vajalik arendus- ja hooldusvõimekus | Vajalik seadistamise ja halduse oskus | Partner katab analüüsi, arenduse ja toe vastavalt kokkuleppele |
| Ajakulu | Võib olla aeglane, kui kogemus puudub | Alustamine on sageli kiirem | Sõltub lähteülesandest ja süsteemide valmisolekust |
| Andmete tundlikkus | Kontroll jääb täielikult ettevõttele | Tuleb kontrollida pakkuja õigusi ja andmekäitlust | Vastutus tuleb lepingus ja tehnilises lahenduses täpselt määrata |
| Paindlikkus | Kõrge, kui meeskond oskab lahendust hooldada | Piiratud pistikprogrammi võimalustega | Kõrge, sest lahendus kujundatakse protsessi järgi |
| Sobivus | Ettevõttele, kellel on püsiv tehniline kompetents | Standardse töövoo jaoks | Kui ühendus on ärikriitiline või sisaldab erandeid |
Valmislahendus on hea lähtekoht, kui platvormil on usaldusväärne pistik ning ettevõtte protsess vastab selle võimalustele. Piirang tuleb nähtavale siis, kui vaja on erandlikku hinnastamist, keerukamat andmevastendust või täpset veakäsitlust.
Ise ehitamine võib olla mõistlik, kui meeskond tunneb mõlemat süsteemi ja suudab lahendust ka pärast lansseerimist hooldada. Partner tasub varakult kaasata, kui lähteülesanne on ebaselge, andmevooge on mitu või ühenduse tõrge mõjutaks tellimusi ja kliendikogemust. WordPressi erilahenduste puhul on üks võimalik lähtekoht vDisaini WordPressi arendus, mis hõlmab ka kohandatud PHP-põhist arendust ja süsteemide ühendamist.
Kokkuvõte ja järgmised sammud
Enne API-liidestamise käivitamist kontrolli seitset punkti:
- Ärieesmärk: tead täpselt, milline käsitöö või risk peab vähenema.
- API pakkuja: oled välja selgitanud, milline süsteem ühendust pakub ja millise dokumentatsiooniga.
- Autentimine: ligipääsud, õigused ja võtmete haldus on määratud.
- Andmemudel: väljad, identifikaatorid ja andmevormingud on süsteemide vahel joondatud.
- Veahaldus: katkestused, korduspäringud ja puuduvad andmed on läbi proovitud.
- Seire: logid, teavitused ja tervisekontrollid töötavad.
- Dokumentatsioon: meeskond teab, kuidas ühendus toimib ja mida teha tõrke korral.
Juba täna saad koostada ühe lehekülje pikkuse integratsioonikaardi. Kirjuta sinna andmeallikad, sihtsüsteemid, liikuva info liik, vastutaja, eelarve ja esimene kontrollpunkt pärast lansseerimist.
Enne arenduse algust vasta ka neljale küsimusele: kes omab andmeid, milline on SLA nõue, kuidas teavitatakse kasutajaid katkestusest ja millal tehakse esimene ülevaatus pärast lansseerimist? Kui need vastused puuduvad, on tehniline plaan tõenäoliselt veel liiga üldine. Järgmises käsitluses saab vaadata lähemalt konkreetseid tööriistu, REST-i ja GraphQL-i valikut ning X-tee teenuseid.
vDisain aitab kaardistada ettevõtte andmevood, valida sobiva liidestusviisi ning arendada ühendusi e-poodide, majandustarkvara ja laohaldussüsteemidega. Kui soovid oma käsitsitööd vähendada, kirjelda olukorda ja tutvu vDisaini lahendustega, et leppida kokku järgmine praktiline samm.
