Mis on API (rakendusliides)?

API lühidalt

Mis on API? Rakendusliides on kirjalik kokkulepe kahe tarkvara vahel: millisele aadressile pöörduda, mis kujul andmeid saata, kuidas end tõendada ja mida tähendab vastuseks tulnud viga. Kui see kokkulepe on olemas, saab süsteem A küsida süsteemilt B andmeid ilma inimese vahelesegamiseta.

Termin tuleb ingliskeelsest sõnast application programming interface, eesti keeles kasutatakse ka sõna rakendusliides. Tähtis on, et API ei ole fail, vahendaja ega andmebaas. Ta on uks, mille kaudu need andmed liiguvad, ja uksel on lukk.

Kuidas API töötab

Enamik tänapäeva liidesi on HTTP-põhised. RFC 9110 määrab, mida tähendavad meetodid nagu GET ja POST ning olekukoodid nagu 200, 401 ja 503. See on kasulik teada, sest just nende koodide peale ehitatakse veakäsitlus: 401 tähendab, et tunnus on vale, 503 seda, et vastaspool on üle koormatud ja päringut tasub hiljem korrata.

Liidese kirjeldus pannakse kirja masinloetava failina. Levinuim vorming on OpenAPI 3.1, millest saab genereerida dokumentatsiooni, testkliendi ja tüübid. Kui vastaspool ei suuda kirjeldust anda, on see märk sellest, et liides on improvisatsioon ja integratsioon saab olema kallis.

Praktikas on neli asja, mis tuleb enne kirjutamist kokku leppida:

1. Autentimine

   Kas võti, OAuth2 või mTLS-sertifikaat. Kes hoiab saladust ja kuidas seda vahetatakse.

2. Andmete vorm

   Kuupäeva formaat, summa valuuta, isiku- ja registrikoodi pikkus. Need kolm tekitavad kõige rohkem vaidlusi.

3. Veakäsitlus

   Mida teha, kui vastaspool ei vasta. Mitu katset, kui pikk ootamine, kuhu läheb ebaõnnestunud sõnum.

4. Korduste välistamine

   Iga päring peab kandma tunnust, mille järgi saab aru, kas see on juba töödeldud. Ilma selleta tekivad topeltkanded.

Näide Eesti ettevõttest

Väikeettevõte täidab kliendivormi jaoks ettevõtte nime, registrikoodi ja aadressi käsitsi. Äriregistri avaandmete teenus annab samad andmed masinloetavalt, seega nimi ja registrikood saab vormi automaatselt.

See on üks väike liides, aga kasu on kohe mõõdetav: iga sisestus on üks võimalus kirjaviga teha, ja vale registrikood läheb hiljem arvele. Sama muster kordub arvete, maksete ja e-kirjadega. Millised liidesed Eesti ettevõttes päriselt vajalikud on, on kirjas artiklis API integratsioonid.

Millal API-d ei ole vaja

• Üks kord aastas. Kui andmeid vahetatakse korra aastas, piisab CSV-failist ja inimesest, kes selle üles laeb.
• Vastaspool ei paku liidest. Kui partneril on ainult e-post, ei ole mõtet ehitada robotit, mis e-kirju loeb, enne kui on kontrollitud, kas liides on tõesti olemas.
• Vajadus on ainult lugeda. Lugemiseks piisab sageli avaandmete massfailist, mis on lihtsam ja odavam kui reaalajas päring.
• Andmed on isikuandmed ja õiguslik alus puudub. Liides ei anna luba andmeid töödelda. Kui töötlemise alus on küsimärgi all, vaata isikuandmete määratlust enne, kui toru valmis ehitatakse.

Töömaht ja kulu

Minu hinnang: ühe liidese esimene versioon on tavaliselt kolm kuni kümme päeva, kui vastaspool on dokumenteeritud ja testkeskkond olemas. Aega kulub päringutele vähem kui veakäsitlusele, logidele ja sellele, et keegi märkaks, kui öine vahetus katkes.

Kui liideseid on mitu, kasvab töö mitte liitmise, vaid korrutamise teel: iga uus allikas toob uue autentimise, uue veakäitumise ja uue viisi, kuidas andmed valed on. Seepärast on mõistlik alustada ühest ja kirjutada iga liidese juurde, mida ta tagastab, kui vastaspool vastab veaga. Kui liides on osa suuremast arendusest, vaata tarkvaraarenduse lehte.