Kas yra API? Paprastas vadovas programų kūrėjams

API (application programming interface) – tai apibrėžtas būdas, kuriuo viena programinės įrangos dalis prašo kitos duomenų arba paveda jai ką nors padaryti. Jūsų programa siunčia užklausą sutartu formatu – „duok rytojaus rezervacijas“, „nuskaityk 20 € nuo šios kortelės“, „apibendrink šį tekstą“ – o kita sistema grąžina struktūrizuotą atsakymą. API yra tai, kaip programos dalys tarpusavyje bendrauja ir kaip jūsų programa naudoja išorines paslaugas, pavyzdžiui, mokėjimus, el. paštą, žemėlapius ir DI.

Kodėl API svarbūs kuriant su DI

Beveik kiekviena naudinga programa sudaryta iš dalių, kurios bendrauja per API:

• Jūsų programos viduje naršyklės ekranai kviečia jūsų backend API, kad įkeltų ir išsaugotų duomenis.
• Už jūsų programos ribų jūsų backend kviečia kitų įmonių API: Stripe mokėjimams, el. pašto teikėjas kvitams siųsti, DI modelio teikėjas tekstui generuoti.

Kai prašote DI kūrėjo „priimti mokėjimus“ ar „pridėti DI santrauką“, jis iš tikrųjų rašo kodą, kuris kviečia API. Žinojimas pagrindų padeda suprasti, ko DI iš jūsų reikia (paprastai paskyros toje paslaugoje ir API rakto), kur gali nutikti klaidų ir kiek tai kainuos.

Kasdienė analogija

Pagalvokite apie restoraną. Jūs neinate į virtuvę gaminti. Perskaitote meniu, pasakote padavėjui, ko norite, tokiu būdu, kurį virtuvė supranta, ir padavėjas atneša jūsų maistą – arba praneša, kad patiekalas baigėsi.

• Meniu yra API dokumentacija: sąrašas, ko galite paprašyti ir kaip.
• Padavėjas yra API: vienintelis sutartas būdas, kuriuo užklausos įeina ir atsakymai išeina.
• Virtuvė yra kita sistema: jums nereikia žinoti, kaip ji veikia viduje.
• Jūsų užsakymas yra užklausa; lėkštė – atsakymas.

Virtuvė gali keisti krosnis ir personalą, nepaveikdama jūsų, jei meniu nesikeičia. Tai tikroji API vertė: ji leidžia dviem sistemoms dirbti kartu, nei vienai nereikia žinoti, kaip kita sukurta.

Kaip veikia žiniatinklio API užklausa

Dauguma API, su kuriais susidursite, yra žiniatinklio API, veikiantys per HTTP – tą patį protokolą, kurį naudoja jūsų naršyklė. Kiekviena užklausa turi kelias dalis:

Ir kiekvienas atsakymas turi:

JSON (JavaScript Object Notation) yra paprastas tekstinis formatas su pavadinimais ir reikšmėmis figūriniuose skliaustuose. Tai standartinis būdas, kuriuo žiniatinklio API keičiasi duomenimis.

REST: dažniausias stilius

REST – tai plačiai naudojama žiniatinklio API projektavimo konvencija. Kiekvienas daiktų tipas turi savo URL, o standartiniai metodai nurodo, ką su juo darote. Štai kaip galėtų atrodyti rezervacijų programos REST API:

PUT taip pat egzistuoja ir pagal konvenciją pakeičia visą įrašą, o PATCH keičia tik jūsų nurodytus laukus.

Dažniausiai matomi statuso kodai:

Kai jūsų programa sugenda, statuso kodas dažnai yra greičiausia užuomina. 401 iš mokėjimo teikėjo paprastai reiškia trūkstamą ar neteisingą API raktą; 429 reiškia, kad kviečiate per dažnai.

REST nėra vienintelis stilius – egzistuoja ir GraphQL bei RPC stiliaus API – bet REST naudoja dauguma paslaugų ir DI sukurtų backend.

Pavyzdys: rezervacijos patvirtinimas

Kai klientas užsisako kirpimą grožio salono programoje, per vieną ar dvi sekundes gali įvykti keletas API kvietimų:

1. Naršyklės rezervacijos puslapis siunčia POST /api/bookings su paslauga, laiku ir kliento duomenimis į jūsų backend.
2. Jūsų backend patikrina, ar laikas laisvas, išsaugo rezervaciją duomenų bazėje ir grąžina 201 Created.
3. Jūsų backend iškviečia el. pašto teikėjo API su savo paslaptiniu raktu: „išsiųsk šį patvirtinimą adresu lena@example.com“.
4. Jei yra užstatas, jūsų backend paprašo mokėjimo teikėjo API sukurti apmokėjimo sesiją ir nukreipia klientą ten.
5. Vėliau mokėjimo teikėjas kviečia jūsų programą pranešti, kad mokėjimas sėkmingas. Tas atvirkštinis kvietimas yra webhook.

Pirmieji du žingsniai yra jūsų pačių API tarp frontend ir backend. 3–5 žingsniai yra trečiųjų šalių API.

Pagrindiniai terminai paaiškinti

Dažnos klaidos ir mitai

• Slaptų raktų įdėjimas į frontend. Viskas kode, kuris veikia naršyklėje, matoma kiekvienam, kas apsilanko svetainėje. Slaptus raktus privalo laikyti serveryje, aplinkos kintamuosiuose ar paslaptyse.
• Raktų įklijavimas į pokalbį. Pokalbio istorija gali būti saugoma. Naudokite savo įrankio paslapčių funkciją ir pakeiskite bet kurį atskleistą raktą.
• Prielaida, kad API nemokamas. Daugelis API apmokestina pagal užklausą ar naudojimo vienetą – DI modelių API skaičiuoja pagal žetonus. Patikrinkite kainas ir nustatykite išlaidų ribas. Žr. kaip naudoti LLM API.
• Gedimų netvarkymas. Išorinės paslaugos sugenda, nebaigia darbo laiku ir pasiekia ribas. Prašykite protingų klaidų pranešimų ir pakartojimų.
• Pasitikėjimas naršykle. Jūsų pačių API turi pats tikrinti leidimus. Mygtuko paslėpimas nesustabdo to, kas tiesiogiai kviečia galutinį tašką.
• Tiesioginių raktų naudojimas testuojant. Naudokite testinio režimo raktus, kol būsite pasiruošę paleisti.

Ką paprašyti DI kūrėjo

• „Kurias išorines API naudoja ši programa ir kiek kainuoja kiekviena?“
• „Kviesk mokėjimo API tik iš serverio. Nuskaityk raktą iš aplinkos kintamojo.“
• „Išvardink kiekvieną mūsų API galutinį tašką, ką jis daro ir kas gali jį kviesti.“
• „Serveryje patikrink, ar prisijungęs vartotojas yra rezervacijos savininkas prieš ją atnaujinant ar trinant.“
• „Jei el. pašto API sugenda, vis tiek išsaugok rezervaciją ir įrašyk klaidą į žurnalą.“
• „Kol kas naudok teikėjo testinį režimą.“

API Mythex platformoje

Mythex gali sukurti jūsų pačių API – kaip žiniatinklio programos dalį arba kaip atskirą backend Node, Python (FastAPI), C# ar Java, veikiantį kartu su jūsų frontend – ir parašyti kodą, kuris kviečia išorines paslaugas. Raktus pridedate kaip projekto paslaptis, o ne pokalbyje, ir jie pasiekiami jūsų programai peržiūroje bei paskelbus. Dokumentacijoje yra receptai integruoti bet kurį API ir sukurti REST API backend.

Klausimai