Integratsioon ebaõnnestub harva ilusa ilmaga ja peaaegu alati siis, kui teine pool on maas, aeglane või saadab midagi ootamatut. Ehitame liidesed, mis eeldavad seda kõike ja taastuvad ise.
Kasvavas ettevõttes ei osteta süsteeme korraga. Müük valis oma tööriista, raamatupidamine oma, ladu sai omaenda programmi ja e-pood tuli neljandast kohast. Iga valik oli omal ajal õige. Probleem tekib alles siis, kui sama tellimus peab jõudma neljast kohast läbi ja seda teeb keegi käsitsi — kopeerides numbrit ühest aknast teise.
Liidestus ei ole seepärast tehniline projekt, vaid otsus selle kohta, kus andmed päriselt elavad ja kes tohib neid muuta. Kui see küsimus on vastamata, ühendab liidestus kaks süsteemi ja tekitab kolmanda tõeversiooni. Meie alustame sellest küsimusest, mitte API dokumentatsioonist.
Enamik liidestusi kuulub ühte kuuest rühmast. Erinevus on selles, kui palju teine pool koostööd teeb — ja just see, mitte kood, määrab tavaliselt maksumuse.
Kui teie süsteemil ei ole liidest, mille kaudu temaga rääkida, ehitame selle. Versioonitud, dokumenteeritud OpenAPI kirjeldusega ja autentimisega, mis ei ole jagatud parool.
Välise teenuse ühendamine teie süsteemiga koos kõige selle juurde kuuluvaga: korduskatsed, piirmäärad, versioonivahetused ja see, mis juhtub siis, kui teine pool vastab aeglaselt või valesti.
Kliendi- ja äriandmete sünkroonimine suuremate platvormidega — Salesforce, HubSpot, SAP, Microsoft Dynamics, NetSuite — nii et igas süsteemis on sama klient, mitte neli sarnast kirjet.
Saadetiste loomine, pakiautomaatide valik ja jälgimisinfo reaalajas. Omniva, DPD, Venipak, Smartpost, DHL ja UPS — koos sellega, et tellimuse staatus ei jää rippuma, kui veopartneri liides on maas.
Stripe, PayPal, Apple Pay, Google Pay ja Eesti pangalingid. Maksed on koht, kus korduskatse ei tohi tähendada topeltmakset — idempotentsus ja lepitus on siin osa tööst, mitte lisa.
Keelemudelite ja masinõppeteenuste ühendamine olemasoleva süsteemiga seal, kus need end ära tasuvad. Koos kulukontrolli, varuvariandi ja selge piiriga, mida mudelile saata tohib.
Liidese stiil valitakse selle järgi, mida teine pool pakub, mitte selle järgi, mis on uuem. Pärandsüsteemidega tähendab see sageli SOAP-i ja failivahetust — ja see on korralikult tehtuna täiesti töökindel.
Liidestuse põhjendus ei ole see, et süsteemid võiksid omavahel rääkida. Need neli on mõõdetavad enne ja pärast — ja kui ükski neist ei kehti, ei ole liidestust vaja.
Suurim kulu ei ole litsents, vaid inimese aeg, mis kulub numbri tõstmisele ühest süsteemist teise.
Kui igal süsteemil on oma versioon kliendist, siis otsust ei saa usaldada ühegi peale.
Liidestus, mille katkemisest saate teada kliendilt, on halvem kui liidestus, mida ei ole — sest te arvate, et see töötab.
Partnerid muudavad oma API-sid. Küsimus on ainult selles, kas te saate sellest teada enne või pärast.
Liidestus näeb pakkumises alati lihtne välja, sest raske osa ei ole ühendamine, vaid tõrked. Küsige seepärast, mis juhtub siis, kui teine pool on maas: kas sõnum läheb järjekorda või kaob. Küsige, kuidas välditakse sama tellimuse kahekordset töötlemist. Küsige, kust te näete, et liidestus töötab — kui vastus on „klient annab teada”, siis monitooringut ei ole.
Ja küsige, mis juhtub siis, kui partner oma API-d muudab. Versioonitud leping ja simuleeritud partner testides on vahe selle vahel, kas muudatus avastatakse testkeskkonnas või reedel toodangus.
Eeldame, et teine pool on maas, aeglane või vastab valesti. Järjekorrad, korduskatsed ja idempotentsed kirjutamised on lähtepunkt, mitte hilisem parandus.
Simuleerime partneri liidese, nii et teie meeskond saab testida igal ajal — ka siis, kui partneri testkeskkond on kinni või seda ei ole olemas.
Iga liidestus antakse üle koos häiretega. Katkestusest saate teada enne, kui klient jõuab helistada.
Kui korralikku API-t ei ole ja jääb failivahetus või brauseriautomaatika, teeme selle ära — aga ütleme ette, mis see hooldusena maksab.
API võtmed, repositooriumid ja pilvekontod on teie omad. Liidestus ei tohi olla põhjus, miks te tarnijat vahetada ei saa.
Asume Tallinnas, samas ajavööndis ja samas lepinguraamistikus. Andmed jäävad soovi korral täielikult EL-i.
Sõnum läheb järjekorda ja saadetakse uuesti kasvava viivitusega. Ükski päring ei kao ja midagi ei töödelda kaks korda, sest kirjutamised on idempotentsed. Kui katkestus kestab, tuleb häire enne, kui klient jõuab helistada.
Jah. Failivahetus, andmebaasi vaated, e-kirjade parsimine ja vajadusel brauseripõhine automatiseerimine on kõik toimivad lahendused. Ütleme ausalt, milline neist on habras ja mida see hooldusena maksab.
Hästi dokumenteeritud API puhul kaks kuni neli nädalat koos testide ja monitooringuga. Halvasti dokumenteeritud või ebastabiilse partneri puhul kulub suurem osa ajast partneri käitumise väljaselgitamisele, mitte koodile.
Seda ei otsusta meie, vaid see, mida teine pool pakub. REST on täna vaikevalik: lihtne, vahemällu salvestatav ja kõik oskavad seda. GraphQL tasub end ära siis, kui klient vajab igal ekraanil erinevat lõiget samadest andmetest ja päringute arv muidu plahvatab. SOAP tuleb ette pangandus- ja riigisüsteemides ning on korralikult tehtuna igati töökindel — see ei ole halb valik, vaid vanem.
Sinna juurde käivad veel webhook’id, kui teine pool tahab ise teatada, mitte oodata küsimist, ja failivahetus, mis on paljudes vanemates süsteemides ainus tee. Kui ehitame API-t teie süsteemile, on vastus tavaliselt REST koos OpenAPI kirjeldusega.
Jagatud paroole ja igavesti kehtivaid võtmeid me ei kasuta. Masinatevaheline suhtlus käib OAuth2 klienditunnustega, mille kehtivus on piiratud ja mida saab välja vahetada ilma koodi muutmata. Iga liidestus saab oma tunnused ja ainult need õigused, mida ta päriselt vajab — nii ei ava üks lekkinud võti kogu süsteemi.
Saladused hoitakse võtmehoidlas, mitte konfiguratsioonifailis ega repositooriumis. Kõik käib TLS-i peal, päringud on logitud koos sellega, kes ja millal, ning isikuandmeid sisaldavad väljad on logidest välja filtreeritud.
Seda juhtub, ja tavaliselt ilma korraliku etteteatamiseta. Kaitse on kahekihiline. Esiteks on leping versioonitud, nii et partneri uus versioon ei asenda vana samal hetkel. Teiseks jooksevad lepingutestid, mis võrdlevad partneri tegelikku vastust sellega, mida meie kood eeldab — need annavad märku testkeskkonnas, mitte toodangus.
Kui muudatus on siiski läbi läinud, hoiab järjekord ebaõnnestunud sõnumid alles. Pärast paranduse paigaldamist saadetakse need uuesti ja andmed jõuavad kohale — midagi ei ole vahepeal kadunud.
Jah, ja see on kavandatud nii. Kood on teie repositooriumis, API võtmed ja pilvekontod teie nimel, ning liidestus antakse üle koos OpenAPI kirjelduse, käitusjuhendi ja monitooringu seadistusega. Üleandmine on ligipääsu muudatus, mitte migratsiooniprojekt.
Kui soovite, jätkame tugilepinguga, kus meie monitooringut ja partnerite muudatusi jälgime. Mõlemad variandid on tavalised ja valik jääb teile — me ei ehita liidestust nii, et selle hooldamiseks oleks meid vaja.
Kirjeldage oma olukorda paari lausega. Vastame ühe tööpäeva jooksul.