API və FastAPI sadə sözlərlə

API - proqramların bir-birinə müraciət etmə üsuludur. Biri xahiş edir, digəri cavab verir. Marketpleys nümunəsində sorğunun nədən ibarət olduğunu, JSON cavabını necə oxumağı və Claude Code xarici verilənlər mənbəyini qoşanda nəyi yoxlamaq lazım olduğunu araşdıraq. Sonda qısaca FastAPI ilə burada harada qarşılaşa biləcəyinizi dəqiqləşdirəcəyik.

API sadə sözlərlə nədir

API (Application Programming Interface) - proqram interfeysidir. O, əlçatan əməliyyatları və onlara müraciət qaydalarını müəyyən edir. API təkcə ayrı-ayrı tətbiqlərdə deyil, kitabxanalarda, əməliyyat sistemində, brauzerdə də var. Onun vasitəsilə proqram başqa proqramdan və ya onun bir hissəsindən nəsə etməyi xahiş edib nəticə ala bilər. Burada əsasən ünvan üzrə müraciət olunan şəbəkə API-lərindən danışacağıq.

Restoranı təsəvvür edin. Siz müştəri kimi mətbəxə getmir və aşpaza necə bişirməyi izah etmirsiniz - ofisianta menyudan nə istədiyinizi deyirsiniz, o, sifarişi mətbəxə ötürür və sizə hazır yeməyi gətirir. API - ofisiantdır. Klient proqram onun vasitəsilə sifariş verir, mətbəx (başqa proqram) isə onu yerinə yetirir. İçəridə hər şeyin necə qurulduğunu bilməyiniz lazım deyil - menyunu bilmək, nə istəyə biləcəyinizi və cavabda nə gələcəyini anlamaq kifayətdir.

Mahiyyətcə API müqavilədir: "mənə belə müraciət etmək olar, cavabda isə filan nəticəni qaytaracağam".

İngilis dilində qısa zarafat videosu da var - "How API work". Bu, eyni fikrə illüstrasiyadır, mövzunun izahı deyil. Lazım olan hər şey aşağıdakı mətndədir.

Marketpleys nümunəsində sorğu və cavab

Təchizatçının malları öz proqramından ötürdüyü marketpleysi təsəvvür edin. Minlərlə mövqeyi saytın düymələri ilə köçürmək əlverişsizdir, ona görə də marketpleys API vasitəsilə proqram əməliyyatları təqdim edir. Məsələn, POST /products məhsul əlavə edir, GET /reports isə hesabat qaytarır.

Əlçatan əməliyyatın ünvanına endpoint deyilir. Sorğunu başa düşmək üçün həm ünvana, həm də HTTP metoduna baxırlar. GET /products və POST /products fərqli işlər görə bilər. GET adətən oxumaq üçün, POST isə verilənləri emal üçün göndərməkdən ötrü istifadə olunur.

Verilənlər çox vaxt JSON formatında ötürülür. Fiqurlu mötərizələr obyektin sahələrini birləşdirir, sətirlər dırnaq içində yazılır, obyektlərin siyahısı isə kvadrat mötərizədə:

{
  "name": "Masa lampası",
  "price": 15000,
  "count": 350
}

Klient sorğu göndərir, server onu emal edir və cavab qaytarır. Aşağıda tam HTTP paketi yox, mübadilənin qısaldılmış sxemi var:

POST /products
{ "name": "Masa lampası", "price": 15000, "count": 350 }

201 Created
{ "id": 4567, "status": "added" }

201 Created - cavabın statusudur, altındakı JSON isə nəticəni daşıyan gövdədir. Real API-də sənədlər endpoint-i, metodu, məcburi parametrləri, başlıqları, cavabın formasını və mümkün xətaları göstərir. Tam verilənlər dəsti ilə yox, bir test obyekti ilə başlamaq daha təhlükəsizdir.

Frontend, backend və onların arasında API

API təkcə müxtəlif tətbiqləri birləşdirmək üçün lazım deyil. Çox vaxt bir tətbiqin özü içəridən iki proqramdan ibarət olur və onlar da API vasitəsilə əlaqə saxlayır.

Frontend - tətbiqin brauzerdə işlədiyiniz hissəsidir. Düymələr, şəkillər, menyular, formalar və səhifənin davranışı ona aiddir. Onun proqram məntiqi adətən JavaScript-də yazılır. O, həm mürəkkəb hesablamaları özü apara, həm də servis tərəfində verilənlər və ya əməliyyat lazım olanda serverə müraciət edə bilər.

Backend - tətbiqin server hissəsidir. O, ödənişləri emal edir, sifarişləri saxlayır, girişi yoxlayır, məhsulları axtarır. İnkişaf zamanı server sizin kompüterinizdə işləyə bilər, dərcdən sonra isə hostinqdə. İstifadəçi onun mənbə kodunu səhifə ilə birlikdə almır. Brauzerə sorğulara cavablar gəlir.

Onlar necə əlaqə saxlayır? Elə həmin API vasitəsilə. Backend endpoint-ləri təkcə xarici təchizatçılara deyil, öz frontend-inə də təqdim edir:

• siz səhifəni açdınız - frontend /products/list endpoint-inə müraciət edir, backend məhsul siyahısını qaytarır, frontend onları səliqə ilə çəkir;
• siz "almaq" düyməsini basdınız - frontend verilənləri /orders endpoint-inə göndərir, backend sifarişi rəsmiləşdirir.

Belə çıxır ki, API vasitəsilə həm müxtəlif tətbiqlər, həm də bir tətbiqin hissələri əlaqə saxlaya bilər. Bu sxemdə brauzer sorğu göndərir, backend verilənlərlə işləyir və nəticəni qaytarır. Verilənlər bazası brauzer üçün birbaşa əlçatan olmalı deyil.

Brauzerdən sorğu

Yuxarıda dedik ki, frontend backend-in endpoint-inə "müraciət edir". Bunun kodda necə göründüyünə baxaq. Brauzerdə bunun üçün daxili fetch funksiyası var. O, lazımi ünvana HTTP sorğusu göndərir və cavabı qaytarır. Cavabın gövdəsi adətən JSON-da gəlir və onu .json() metodu ilə obyektə çevirirlər.

Lokallar kataloqunu götürək - dil və regional ayarların birləşmələrini. Tutaq ki, backend artıq /locales ünvanında siyahını verə bilir, frontend isə onu göstərməlidir. Məsələn, server bunu qaytarır:

[
  { "code": "en-GB", "language": "English", "country": "United Kingdom" },
  { "code": "de-DE", "language": "Deutsch", "country": "Germany" }
]

Cavab necə gəlir

Aşağıdakı fraqment səhifə işləyicisinin asinxron funksiyası daxilində icra olunur. O, verilənləri alır; cədvəlin çıxışı burada göstərilmir.

const res = await fetch("/locales");
if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}
const locales = await res.json();
// İndi locales cədvəl üçün verilənləri saxlayır

Verilənləri oxumazdan əvvəl res.ok-u yoxlayırıq. 404 və ya 500 kimi HTTP xətası özlüyündə fetch-i istisna ilə bitməyə məcbur etmir. Ayrıca şəbəkə sorğusunun özü baş tutmaya və ya JSON təhlil olunmaya bilər. Belə fraqmentdən çıxan xətanı səhifənin kodu tutmalı və anlaşılan mesaj göstərməlidir. Bunlar fərqli səbəblərdir, halbuki istifadəçi hər halda verilənləri ala bilməyib. Ətraflı - MDN-in fetch bələdçisində.

Burada gözdən qaçırmaq asan olan bir-iki xırda məqam var:

• standart olaraq fetch GET göndərir - verilənləri almaq üçün sorğu. Digər əməliyyatlar metodla təyin olunur; məsələn, bizim marketpleys yeni məhsulu POST vasitəsilə qəbul edir;
• /locales ünvanı nisbidir. Adi HTTP səhifəsində o, həmin origin-in kökünə müraciət edir. Origin sxem, host və portla müəyyən olunur; serverdə belə marşrut olmalıdır;
• fetch və .json() nəticəni dərhal qaytarmır, ona görə də onlardan əvvəl await yazılır - "cavabı gözlə".

HTML-i fayl kimi file:// vasitəsilə açsanız, /locales yazısı sizin HTTP serverinizin ünvanına çevrilməyəcək. Bu nümunə üçün səhifəni marşrutun reallaşdırıldığı server vasitəsilə açırlar. HTML faylının özü belə marşrut yaratmır.

Frontend və API fərqli origin-lərdə ola bilər. Onda brauzerdən cavabı oxumaq üçün API serveri lazımi girişə CORS vasitəsilə icazə verməlidir. Bu, saytlararası giriş mexanizmidir, istənilən şəbəkə xətasının adı deyil. Səhifəni və API-ni bir origin-də yerləşdirmək nümunəni sadələşdirir, amma bütün tətbiqlər üçün məcburi deyil. Təfərrüatlar MDN-də CORS təsvirindədir.

Brauzerə kim cavab verir

fetch("/locales")-ə kim cavab verir? Backend, və o, mütləq FastAPI ilə Python-da olmalı deyil. API konkret dil yox, proqramlar arasında razılaşmadır. Həmin endpoint-i Node.js, Go və ya Java-da yazırlar. Məsələn, Node.js serverinin işləyicisində hazırlanmış locales massivini qaytarmaq olar. Aşağıda hazır server yox, yalnız işləyicinin fraqmentidir:

// req və res işləyici tərəfindən alınıb, locales əvvəlcədən hazırlanıb
if (req.method === "GET" && req.url === "/locales") {
  res.statusCode = 200;
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.end(JSON.stringify(locales));
}

Kənardan bu, yenə də həmin GET /locales HTTP sorğusudur, cavabda isə 200 statusu və JSON. Frontend-in backend-in nə ilə yazıldığını bilməsinə ehtiyac yoxdur. Ona ünvan, sorğu qaydaları və cavabın formatı lazımdır.

Hansı API-lər olur

API-ləri iki əlamətə görə bölmək rahatdır:

• lokal və şəbəkə - məsələn, kitabxana API-sini proqramın kodundan çağırırlar, şəbəkə API-sinə isə şəbəkə vasitəsilə müraciət edirlər. Şəbəkə açıq internet olmadan, daxili də ola bilər;
• publik və daxili - publik API-lər xarici developer-lər üçün nəzərdə tutulub, daxililər sistemin hissələrini birləşdirir. Publik API də qeydiyyat, ödəniş və icazələr tələb edə bilər.

Veb-API-lər çox vaxt HTTP istifadə edir - sorğu və cavab protokolunu. Adına sənədlərdə rast gələcəyiniz REST API qurmaq yanaşmasını təsvir edir; hər HTTP API avtomatik olaraq REST-ə uyğun deyil. Hələlik cavabdakı status kodunu oxumağı öyrənmək daha faydalıdır:

• 200 - hər şey qaydasındadır;
• 201 - yaradıldı (məsələn, POST-dan sonra yeni obyekt);
• 404 - tapılmadı;
• 401 - sorğuda uyğun autentifikasiya məlumatları yoxdur;
• 429 - həddən artıq çox sorğu;
• 500 - serverin daxili xətası.

Bunun dərinliyinə indi varmamaq olar. Vacib olan sorğu və cavab mübadiləsi ideyasının özünü tutmaqdır. Hələlik bu kifayətdir.

Servisə giriş açarı nə üçün lazımdır

Bir çox servis əvvəlcə API açarı almağı xahiş edir - hesabınız və ya layihənizlə bağlı sətir. Onu sənədlərdə göstərilən üsulla, çox vaxt sorğunun başlığında ötürürlər. Servis girişi yoxlayır və neçə sorğu etdiyinizi hesablaya bilər. Başqa inteqrasiyalarda token sözü ilə qarşılaşacaqsınız. Onun təyinatı oxşardır, amma alınma üsulu, etibarlılıq müddəti və hüquqları fərqli ola bilər.

Uyğun giriş olmadan sorğu icra olunmayacaq; məsələn, server 401 ilə cavab verə bilər. Sorğu tezliyinin aşılması çox vaxt 429 kodu ilə bildirilir. Cavabın dəqiq mənasına və icazə verilən həcmlərə konkret servisin sənədlərində baxırlar. Açar ümumiyyətlə lazım olmayan açıq mənbələr də var.

Hazır API-ni harada axtarmaq

API vasitəsilə tətbiqlərə xəritələr, hava, ödənişlər və çatdırılma qurulur. Açıq sənədlər servisin imkanlarını hələ qoşulmadan əvvəl anlamağa kömək edir. Tapşırığın özündən başlamaq daha yaxşıdır. Hansı verilənlərin lazım olduğunu, onların nə qədər tez-tez yenilənməli olduğunu və onlarla nə edəcəyinizi müəyyən edin.

Axtarış üçün API-lərin və sorğu nümunələrinin kataloqu olan Postman Public API Network-ə baxmaq rahatdır. Tapılmış nümunə sadəcə başlanğıc nöqtəsidir. Ünvanı, formatı, girişi və məhdudiyyətləri yenə də servis sahibinin rəsmi sənədləri ilə tutuşdurun.

FastAPI burada haradadır

FastAPI - Python-da API və veb-serverlər yaratmaq üçün freymvorklardan biridir. O, endpoint-i sizin server kodunuzla bağlaya, sorğunu qəbul edə və JSON cavabı qaytara bilər. FastAPI öz Python backend-inizi yaradanda lazımdır; hazır API-dən istifadə etmək üçün onu öyrənmək tələb olunmur. 7-ci səviyyədə adı tanımaq və bu sərhədi anlamaq kifayətdir.

Claude Code ilə birlikdə bu necə işləyir

Bu anlayışlarla agentin işini qiymətləndirmək daha asandır. O, başqasının API-sinin sənədlərini oxuya, klient sorğusu yaza və ya FastAPI-da sizin API-nizi yarada bilər. Sizin üçün sorğudan səhifədəki verilənlərə qədər konkret yolu görmək vacibdir. Sorğunu kim göndərir, kim cavab verir və cavab necə emal olunur?

Məsələn, zəlzələ radarı üçün USGS-in publik GeoJSON feed-i var. Son bir saatın siyahısının ünvanı:

GET https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson

Aşağıda cavabın strukturu üzrə uydurma hadisə və qısaldılmış sahə dəsti ilə kiçik tədris nümunəsi var. Bunlar USGS-in cari verilənləri deyil:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "mag": 4.2, "place": "Tədris nöqtəsi" },
      "geometry": { "type": "Point", "coordinates": [-122.5, 38.0, 8.0] }
    }
  ]
}

features-də hadisələr massivi yerləşir. features[0].properties.mag yolu birinci hadisənin maqnitudasına aparır. 0 indeksi massivin birinci elementi deməkdir. Koordinatlar "uzunluq, enlik, kilometrlə dərinlik" ardıcıllığı ilə gedir. Agent maqnitudadan nöqtənin ölçüsü, koordinatlardan isə onun yeri üçün istifadə edə bilər. Massiv boşdursa, birinci element yoxdur; maqnituda null-a bərabərdirsə, bu, naməlum kəmiyyətdir, hadisənin sıfır gücü deyil.

Sorğudan sonra nəyi göstərəcəyimizi həll etmək qalır:

Sorğu icra olunarkən səhifə yüklənmə göstəricisini göstərə bilər. Müxtəlif nəticələri yoxlamaq üçün tədris cavablarından istifadə etmək rahatdır. Belə olanda servisin real nasazlığını və ya yeni zəlzələni gözləmək lazım gəlməyəcək.

Claude Code-a tapşırıq indi belə səslənə bilər:

Göstərilən API-dən verilənləri səhifəyə qoş.
Əvvəlcə rəsmi sənədləri yoxla: ünvan, metod,
cavabın formatı və giriş şərtləri. Hansı sahələrdən istifadə etdiyini göstər.
Yüklənməni, boş siyahını və yeniləmə xətasını nəzərə al.
Nasazlıqdan sonra köhnə verilənlərdən istifadə edirsənsə, bunu səhifədə qeyd et.
Gizli açarı klient koduna qoyma.
Nəticəni yoxla və hansı vəziyyətləri yoxlaya bildiyini de.

İşdən sonra təkcə hazır şəklə deyil, sorğunun özünə və yoxlamanın nəticəsinə də baxın. Agentin girişini və səhifənin girişini ayrıca fərqləndirin. MCP Claude Code-a alət qoşa bilər, amma dərc olunmuş tətbiqə öz inteqrasiyası lazımdır. Agentin bağlanmış sessiyası, sorğular tətbiqin özündə reallaşdırılıbsa, saytın sorğularını dayandırmamalıdır.