Çfarë është një API? Udhëzues i thjeshtë për ndërtuesit e aplikacioneve

Një API (application programming interface) është një mënyrë e përcaktuar me të cilën një softuer i kërkon një tjetri të dhëna ose ta bëjë të kryejë një veprim. Aplikacioni yt dërgon një kërkesë në një format të rënë dakord — “më jep rezervimet e nesërme”, “ngarko këtë kartë me 20 €”, “përmblidh këtë tekst” — dhe sistemi tjetër kthen një përgjigje të strukturuar. API-të janë mënyra si pjesët e një aplikacioni flasin me njëra-tjetrën, dhe mënyra si aplikacioni yt përdor shërbime të jashtme si pagesat, email-i, hartat dhe AI-ja.

Pse ka rëndësi API-të kur ndërton me AI

Pothuajse çdo aplikacion i dobishëm përbëhet nga pjesë që komunikojnë përmes API-ve:

• Brenda aplikacionit tënd, ekranet në shfletues thërrasin API-n e backend-it tënd për të ngarkuar dhe ruajtur të dhëna.
• Jashtë aplikacionit tënd, backend-i yt thërret API-të e kompanive të tjera: Stripe për pagesat, një ofrues email-i për faturat, një ofrues modelesh AI për tekst të gjeneruar.

Kur i kërkon një ndërtuesi me AI të “marrë pagesa” ose të “shtojë një përmbledhje me AI”, ajo që bën në të vërtetë është të shkruajë kod që thërret një API. Njohja e bazave të ndihmon të kuptosh çfarë i nevojitet AI-së prej teje (zakonisht një llogari te ai shërbim dhe një çelës API), ku mund të dalin gabime dhe sa do të kushtojnë.

Një analogji e përditshme

Mendo për një restorant. Ti nuk hyn në kuzhinë dhe nuk gatuan vetë. Lexon menunë, i thua kamarierit çfarë do në një mënyrë që kuzhina e kupton, dhe kamarieri të sjell ushqimin — ose të thotë që pjata ka mbaruar.

• Menuja është dokumentacioni i API-t: lista e asaj që mund të kërkosh dhe si.
• Kamarieri është API-ja: mënyra e vetme e rënë dakord me të cilën kërkesat hyjnë dhe përgjigjet dalin.
• Kuzhina është sistemi tjetër: nuk ke nevojë të dish si funksionon brenda.
• Porosia jote është kërkesa; pjata është përgjigja.

Kuzhina mund t’i ndryshojë furrat dhe stafin pa të prekur, për sa kohë menuja mbetet e njëjtë. Kjo është vlera e vërtetë e një API-je: lejon dy sisteme të punojnë bashkë pa qenë nevoja që njëri të dijë se si është ndërtuar tjetri.

Si funksionon një kërkesë API-je në ueb

Shumica e API-ve që do të takosh janë API uebi që punojnë përmes HTTP, i njëjti protokoll që përdor shfletuesi yt. Çdo kërkesë ka disa pjesë:

Dhe çdo përgjigje ka:

JSON (JavaScript Object Notation) është një format i thjeshtë tekst me emra dhe vlera në kllapa kaçurrelë. Është mënyra standarde si shkëmbejnë të dhëna API-të e uebit.

REST: stili më i zakonshëm

REST është një konventë e gjerësisht e përdorur për dizajnimin e API-ve të uebit. Çdo lloj gjëje merr URL-në e vet, dhe metodat standarde tregojnë çfarë i bën. Ja si mund të duket një REST API për një aplikacion rezervimesh:

PUT gjithashtu ekziston dhe, sipas konventës, zëvendëson të gjithë regjistrimin, ndërsa PATCH ndryshon vetëm fushat që dërgon.

Kodet e statusit që do të shohësh më shpesh:

Kur aplikacioni yt prishet, kodi i statusit shpesh është treguesi më i shpejtë. Një 401 nga një ofrues pagesash zakonisht do të thotë një çelës API që mungon ose është i gabuar; një 429 do të thotë se po thërret shumë shpesh.

REST nuk është i vetmi stil — ekzistojnë edhe GraphQL dhe API-të në stilin RPC — por REST është ajo që përdorin shumica e shërbimeve dhe backend-eve të ndërtuar me AI.

Një shembull i punuar: konfirmimi i një rezervimi

Kur një klient rezervon një prerje flokësh në një aplikacion sallonesh, mund të ndodhin disa thirrje API brenda një ose dy sekondash:

1. Faqja e rezervimit në shfletues dërgon POST /api/bookings me shërbimin, orën dhe detajet e klientit te backend-i yt.
2. Backend-i yt kontrollon që slot-i është i lirë, e ruan rezervimin në bazën e të dhënave, dhe kthen 201 Created.
3. Backend-i yt thërret API-n e një ofruesi email-i me çelësin e tij sekret: “dërgo këtë konfirmim te lena@example.com.”
4. Nëse ka një depozitë, backend-i yt i kërkon API-së së ofruesit të pagesave të krijojë një sesion checkout dhe e dërgon klientin atje.
5. Më vonë, ofruesi i pagesave thërret aplikacionin tënd për të thënë se pagesa u krye. Ai thirrje e kthyer është një webhook.

Hapat e parë janë API-ja jote e brendshme mes frontend-it dhe backend-it. Hapat 3–5 janë API të palëve të treta.

Termat e zakonshëm të shpjeguar

Gabime dhe keqkuptime të zakonshme

• Vendosja e çelësave sekret në frontend. Çdo gjë në kod që ekzekutohet në shfletues mund të shihet nga kushdo që viziton faqen. Çelësat sekret duhet të mbeten në server, në variablat e mjedisit ose sekretet.
• Ngjitja e çelësave në chat. Historia e chat-it mund të ruhet. Përdor në vend të kësaj veçorinë e sekreteve të ndërtuesit dhe rrotullo çdo çelës që ke ekspozuar.
• Supozimi se API-ja është falas. Shumë API-të paguhen për kërkesë ose për njësi përdorimi — API-të e modeleve AI paguhen sipas tokenëve. Kontrollo çmimet dhe vendos kufij shpenzimesh. Shih si të përdorësh API-të LLM.
• Mos trajtimi i dështimeve. Shërbimet e jashtme bien, skadojnë dhe arrijnë kufij. Kërko mesazhe gabimi të arsyeshme dhe rifillime.
• Besimi te shfletuesi. API-ja jote duhet të kontrollojë vetë lejet. Fshehja e një butoni nuk ndalon dikë të thërrasë direkt endpoint-in.
• Përdorimi i çelësave live gjatë testimit. Përdor çelësat e modalitetit test derisa të jesh gati për lançim.

Çfarë t’i kërkosh ndërtuesit tënd me AI

• “Cilat API të jashtme përdor ky aplikacion, dhe sa kushton secila?”
• “Thirr API-n e pagesave vetëm nga serveri. Lexo çelësin nga një variabël mjedisi.”
• “Listo çdo endpoint në API-n tonë, çfarë bën dhe kush lejohet ta thërrasë.”
• “Kontrollo në server që përdoruesi i kyçur është pronari i rezervimit përpara se ta përditësosh ose fshish.”
• “Nëse API-ja e email-it dështon, ruaj rezervimin gjithsesi dhe regjistro gabimin.”
• “Përdor për tani modalitetin test të ofruesit.”

API-t në Mythex

Mythex mund të ndërtojë API-n tënde — si pjesë e një aplikacioni uebi, ose si një backend i veçantë në Node, Python (FastAPI), C# ose Java që punon krah frontend-it tënd — dhe të shkruajë kodin që thërret shërbime të jashtme. Çelësat e tyre i shton si sekrete të projektit dhe jo në chat, dhe aplikacioni yt i ka të disponueshëm në preview dhe pasi të publikohet. Dokumentacioni ka receta për integrimin e çdo API-je dhe ndërtimin e një backend-i REST API.

Pyetje