API – programų sąsaja, nusakanti, kaip viena programos dalis ar sistema gali naudotis kitos funkcijomis ir duomenimis. Santrumpa kilusi iš angliško termino „Application Programming Interface“. Žmogus svetainėje spaudžia mygtukus, o programa per API kreipiasi pagal dokumentuotas taisykles: kokį veiksmą galima atlikti, kokius duomenis pateikti ir kokio atsakymo tikėtis.
Pavyzdžiui, orų programėlė gali gauti prognozės duomenis iš jų teikėjo API ir parodyti juos savo ekrane. API nėra pati prognozė ar visas programėlės vaizdas. Tai sąsaja, per kurią pasiekiama numatyta funkcija. Toliau aptariame ir bendrą API sąvoką, ir dažnai sutinkamą interneto API užklausos bei atsakymo eigą.
API paprastai: sutarta sąsaja, o ne visa sistema
MDN API apibrėžime akcentuojamos programoje esančios funkcijos ir taisyklės, leidžiančios su ja sąveikauti programiškai. Tai padeda naudotis galimybe neperrašant viso jos veikimo iš naujo. Programuotojui nebūtina žinoti kiekvienos vidinės detalės, tačiau būtina suprasti sąsajos naudojimo sąlygas.
Kasdienė analogija: meniu nurodo, ką galite užsisakyti, o užsakymo taisyklės – ką turite pasakyti. Tačiau vien meniu nepagamina maisto. Panašiai dokumentuota API aprašo galimybes, o jas įgyvendina programinis kodas ir, kai reikia, serveris. Ši analogija tik padeda suprasti sąsają; ne kiekviena API yra užklausa kitam interneto serveriui.
Ar visos API veikia internetu?
Ne. MDN žiniatinklio API įvade atskiriamos naršyklėje esančios galimybės ir trečiųjų šalių paslaugų sąsajos. Pavyzdžiui, programa gali naudotis naršyklės dokumento elementų valdymo sąsaja. Kitu atveju jai reikia kreiptis į išorinės paslaugos serverį.
| Sąvoka | Ką ji reiškia? | Su kuo nepainioti? |
|---|---|---|
| API. | Programiškai naudojama sąsaja ir jos taisyklės. | Ne vien interneto adresas ar duomenų bazė. |
| Interneto API. | Per tinklą pasiekiama paslaugos sąsaja. | Ne visos API privalo veikti per tinklą. |
| API integracija. | Įgyvendintas sistemų sujungimas naudojant sąsają. | Ne vien raktas ar užrašas „turime API“. |
| Dokumentacija. | Adresų, veiksmų, parametrų ir atsakymų aprašas. | Ji nepakeičia veikiančio ryšio ir klaidų apdorojimo. |
Kaip atrodo interneto API užklausa ir atsakymas?
„GitHub“ REST API pradžios gide aprašomi užklausos elementai: HTTP metodas, kelias, antraštės ir prireikus parametrai bei autentifikavimas. Dokumentacija taip pat parodo laukiamus atsakymus. Ne kiekvienam veiksmui reikia visų šių elementų.
- Programa parenka veiksmą: pavyzdžiui, gauti vietovių sąrašą.
- Paruošia užklausą: naudoja dokumentacijoje nurodytą adresą, metodą ir reikiamus parametrus.
- Paslauga apdoroja užklausą: patikrina, ar ji tinkama ir leidžiama.
- Programa įvertina atsakymą: perskaito būseną, duomenis ar klaidos pranešimą.
- Parodo rezultatą: iš duomenų sudaro žmogui suprantamą ekraną arba įvykdo kitą numatytą žingsnį.
Dažnas duomenų pateikimo formatas yra JSON. Tai struktūruotas tekstas, kurį programa gali perskaityti pagal laukų pavadinimus. Jis nėra gražus programėlės ekranas: vaizdą iš gautų duomenų sukuria ją rodanti programa.
Tikras Lietuvos pavyzdys: Meteo LT API
Lietuvos hidrometeorologijos tarnybos API dokumentacijoje nurodyta užklausa GET /places, grąžinanti vietovių sąrašą. Atsakyme aprašyti tokie laukai kaip vietovės kodas, pavadinimas ir koordinatės. Tai konkretus pavyzdys, kaip programai pateikiami duomenys, o ne jau paruoštas orų puslapis.
Dokumentacijoje atskirai aprašytos prognozės, stočių matavimai, duomenų naudojimo sąlygos ir užklausų ribojimas. Todėl „prijungti orus“ reiškia daugiau nei įrašyti vieną adresą: reikia pasirinkti tinkamą duomenų rūšį, nurodyti šaltinį ir pasirūpinti tuo, kas rodoma nutrūkus ryšiui. Šiame straipsnyje gyvos prognozės neteikiame ir išgalvotų meteorologinių rodmenų nerodome.
Ką reiškia atsakymo kodai?
HTTP būsenų aprašas padeda suprasti, ar užklausa pavyko ir kokio pobūdžio kliūtis kilo. Žemiau – pagrindinės reikšmės; konkreti paslauga savo dokumentacijoje gali paaiškinti papildomas aplinkybes.
| Kodas | Bendra reikšmė | Ką pasitikrinti? |
|---|---|---|
| 200. | Užklausa sėkminga. | Ar atsakyme tikrai yra jūsų užduočiai reikalingi duomenys? |
| 401. | Reikia tinkamai autentifikuotis. | Ar pateikti galiojantys prisijungimo duomenys? |
| 403. | Prieiga atsisakyta. | Leidimus ir konkrečios paslaugos klaidos paaiškinimą. |
| 404. | Išteklius nerastas arba jo buvimas neatskleidžiamas. | Adresą, objekto identifikatorių ir prieigos taisykles. |
| 429. | Per daug užklausų. | Taikomą limitą ir dokumentuotą laukimo tvarką. |
Vien skaičiaus 200 nepakanka patvirtinti, kad visa integracijos užduotis atlikta teisingai. Pavyzdžiui, sėkmingai gautas tuščias sąrašas gali būti netinkamas jūsų tikslui. Programa turi tikrinti ir atsakymo turinį.
Raktai, limitai ir saugus pirmas bandymas
Ne visoms API reikia rakto. Kai jo reikia, jis gali suteikti prieigą prie konkrečių galimybių. „GitHub“ saugumo rekomendacijos ragina suteikti tik būtinus leidimus ir nesaugoti slaptų žetonų tiesiogiai kode ar saugykloje. Tikro rakto nedėkite į viešą pavyzdį ar ekrano kopiją.
Užklausų limitai priklauso nuo paslaugos, veiksmo ir prisijungimo būdo. „GitHub“ pavyzdys rodo, kad ribojimas gali būti kelių rūšių. Gavus klaidą, aklas siuntimas vis dažniau jos neišsprendžia.
- Pradėkite nuo skaitymo: dokumentacijoje pasirinkite leistiną duomenų gavimo pavyzdį.
- Naudokite bandomus duomenis: pirmam bandymui nereikia tikrų klientų informacijos.
- Aptarkite klaidas: kas bus rodoma negavus atsakymo ar pasikeitus jo struktūrai?
- Įvertinkite rezultatą: tikrinkite ne tik ryšį, bet ir teisingus laukus bei jų reikšmes.
Dažniausi klausimai
Ar API ir programėlė yra tas pats?
Ne. Programėlė gali naudotis API, tačiau jos ekranai, logika ir naudojimo patirtis sudaro platesnį produktą. API apibrėžia konkrečią programinę sąveiką.
Ar turint API raktą galima daryti viską?
Ne. Galimybes riboja suteikti leidimai, paslaugos taisyklės ir užklausų limitai. Raktas nesuteikia daugiau teisių, nei jam leidžiama.



