API oddiy tilda: dastur boshqa dasturdan nimani, qanday soʻraydi

Odoo hujjatidagi eng qisqa misol bir necha qatordan iborat. Dastur kontragentlar jadvaliga murojaat qiladi: manzilga POST yuboradi, sarlavhada API kalitini beradi, tanada qaysi kontragentlar kerakligini yozadi. Javobga kontragentlar roʻyxati keladi. Shu qisqa almashinuvda API ning deyarli hamma asosiy qismi bor: manzil, harakat, kalit, ikki tomon tushunadigan format va natija haqidagi kod.

Ikki dastur, bitta kelishuv

API ikki dastur oʻrtasidagi kelishuv: bir tomon nimani soʻrashi mumkin, ikkinchisi nimani va qaysi shaklda beradi.

Buni restoranga oʻxshatish mumkin. Menyu oldindan yozib qoʻyilgan, buyurtma esa menyudagi shaklda beriladi. OpenAPI spetsifikatsiyasi HTTP orqali ishlaydigan API ni shunday taʼriflaydi: tilga bogʻliq boʻlmagan standart interfeys. Uning vazifasi odam ham, dastur ham xizmat nimaga qodirligini manba kodiga qaramay tushuna olishi.

Ikki tomonning nomi ham aniq. HTTP standartida mijoz serverga ulanib soʻrov yuboradigan dastur, server esa ulanishni qabul qilib soʻrovga javob beradigan dastur. Brauzer ham mijoz, internet-doʻkonning buyurtma boʻlimi ham. Har bir xabar yo soʻrov, yo javob.

Soʻrov: usul, manzil, sarlavha, tana

Har bir soʻrov toʻrt qismdan tuziladi va har bir qismning oʻz vazifasi bor.

Usul qanday harakat soʻralayotganini aytadi, manzil resursni koʻrsatadi, sarlavhalar kim va qaysi formatda murojaat qilayotganini bildiradi, tana esa maʼlumotning oʻzini olib yuradi. Odoo misolida bu qismlar quyidagicha.

Tana odatda JSON formatida yoziladi. RFC 8259 uni tuzilmali maʼlumotni ketma-ketlashtirish uchun matn formati deb taʼriflaydi. Unda satr, son, mantiqiy qiymat, boʻsh qiymat, obyekt va massiv boʻladi. Matn boʻlgani uchun uni odam ham, dastur ham oʻqiy oladi.

Kalit sarlavhada beriladi: shaxsni tasdiqlash uchun ajratilgan maydonga API kaliti yoziladi. Jadval nomi va amal esa manzilning ichida turadi. Demak, har soʻrov oʻzi bilan kimligini olib keladi, server esa kalitga qarab ruxsatni tekshiradi.

Tana ham qoidaga ega. Odoo hujjatiga koʻra, JSON obyektda yozuvlar roʻyxati qaysi yozuvlar ustida amal bajarilishini bildiradi. Modelning umumiy metodlari uchun bu roʻyxat boʻsh yoki tushirib qoldirilgan boʻladi. Undan keyin amal parametrlari nomi bilan keladi, kontekst, masalan til, ixtiyoriy. Yaʼni “API bor” degan gap yetarli emas: har bir amalning oʻz parametrlari va oʻz javobi boʻladi.

Kalit haqida ham bir nuans bor. Odoo 19 hujjati kalitlar foydalanuvchi profilining xavfsizlik sozlamalarida yaratilishini va uch oydan uzoq muddatli kalit yaratib boʻlmasligini yozadi. Demak, integratsiya bir marta sozlab qoʻyiladigan narsa emas, kalitni almashtirish tartibi ham uning bir qismi.

Ixtiyoriy sarlavhalar ham bor. Bazaning nomini koʻrsatadigan sarlavha kerak boʻlganda ishlatiladi. Murojaat qilayotgan dastur nomini bildiradigan sarlavha esa hujjatda tavsiya etiladi. Kichik narsa, lekin server jurnalida kim nima soʻragani keyin aniqlanishida aynan shu belgilar yordam beradi.

HTTP usullari: oʻqish, yaratish, almashtirish

Usul nomi soʻrovning niyatini bildiradi, lekin uni koʻr-koʻrona ishonib boʻlmaydi.

RFC 9110 sakkizta standart usulni sanaydi: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS va TRACE. Integratsiyada koʻpincha toʻrttasi uchraydi:

• GET maqsadli resursning joriy tasvirini oʻtkazishni soʻraydi.
• POST resurs soʻrov tanasini oʻz qoidasi boʻyicha qayta ishlashini talab qiladi.
• PUT resurs holatini tanadagidek yaratish yoki almashtirishni bildiradi.
• DELETE oʻchirish uchun ishlatiladi.

Standart yana ikki xossani alohida belgilaydi:

• Usul xavfsiz hisoblanadi, agar uning maʼnosi asosan faqat oʻqish boʻlsa: mijoz server holatining oʻzgarishini soʻramaydi va kutmaydi. Standart boʻyicha GET, HEAD, OPTIONS va TRACE xavfsiz.
• Usul idempotent boʻladi, agar bir xil soʻrovni bir necha marta yuborish bir marta yuborgandek maqsadli natija bersa. Bunday usullar: PUT, DELETE va barcha xavfsizlari.

Amaliy oqibat tarmoq uzilganda koʻrinadi. Gipotetik holat: dastur POST bilan yangi mijoz yaratdi, lekin javob yetib kelmadi. Qayta yuborish ikkinchi yozuvni yaratishi mumkin, chunki POST idempotent usullar roʻyxatida yoʻq. PUT ni qayta yuborish esa mantiqan bir xil natijaga olib kelishi kerak. Amalda har bir usul qanday ishlashini server dasturchisi belgilaydi.

Odoo misoli yana bir nuansni koʻrsatadi: u oʻqish uchun ham, yozish uchun ham POST ishlatadi, amal nomi esa manzilda turadi. Usul nomiga qarab API nima qilishini har doim bilib boʻlmaydi, hujjatni oʻqish kerak.

Javob: status kodi va tana

Server javobni uch xonali kod bilan boshlaydi va bu kod soʻrov taqdirini qisqa aytadi.

Kod 100 dan 599 gacha boʻladi, birinchi raqam sinfni bildiradi: 1 axborot, 2 muvaffaqiyat, 3 yoʻnaltirish, 4 mijoz xatosi, 5 server xatosi. Eng koʻp uchraydigan kodlar jadvalda.

401 va 403 koʻp chalkashtiriladi. Birinchisi soʻrov bajarilmadi, chunki haqiqiy kalit yoki login yoʻq degani. Ikkinchisi soʻrov tushunildi, ammo bajarilmaydi degani. Integratsiya sozlayotgan kishi uchun bu farq muhim: birinchi holda kalit tekshiriladi, ikkinchisida ruxsatlar.

Xatoda kod yetarli boʻlmaydi, shuning uchun serverlar tanada tafsilot ham qaytaradi. Odoo hujjatida muvaffaqiyatli javob 200 kodi va metodning JSON natijasi bilan keladi. Xato esa 4xx yoki 5xx kodi va xato nomi, xabari, argumentlari, konteksti hamda texnik tafsilotini oʻz ichiga olgan JSON obyekt bilan keladi. Hujjat misolida notoʻgʻri API kaliti 401 kodi va “Invalid apikey”, yaʼni notoʻgʻri kalit, xabarini beradi.

Muvaffaqiyatli javobning shakli ham oddiy. Hujjatdagi misolda soʻrov kontragent nomlarini soʻraydi, javob esa JSON massiv boʻlib, har elementida yozuv raqami va nomi bor. Dastur bu massivni oʻqib, oʻz ekranida yoki hisobotida koʻrsatadi. Ikki tomon oʻrtasida faqat matn almashinadi, ichki maʼlumotlar bazasi qanday tuzilganini soʻrovchi bilmaydi va bilishi shart emas.

Bitta soʻrovning yoʻli: gipotetik misol

Bitta oddiy soʻrov uch xil holatda uch xil javob olishi mumkin, dastur esa har holatda boshqacha ish tutadi.

Internet-doʻkon dasturi ombor tizimidan mahsulot qoldigʻini soʻraydi, deylik. Bu uydirma misol, manzillar ham shartli. Dastur mahsulotning qoldiq manziliga GET yuboradi va sarlavhada kalitini koʻrsatadi. Hammasi joyida boʻlsa, 200 kodi bilan tanada qoldiq soni keladi.

Mahsulot raqami notoʻgʻri boʻlsa, 404 qaytadi va dastur doʻkon sahifasida “mavjud emas” deb koʻrsatishi mumkin. Kalit eskirgan boʻlsa, 401 keladi va bu holatda dastur qayta urinishning foydasi yoʻqligini bilishi kerak. 503 esa vaqtinchalik: server band, birozdan keyin urinib koʻrish mantiqli. Uchala holat ham bitta soʻrov, lekin dasturning keyingi harakati butunlay boshqacha.

Shartnomani yozib qoʻyish: OpenAPI

OpenAPI API ning “menyu”sini bir hujjatga yozib qoʻyadi.

API ni tasvirlashning keng tarqalgan usuli OpenAPI spetsifikatsiyasi. Uning hujjati JSON yoki YAML formatida yoziladi. U manzillar, usullar, parametrlar va javob shakllarini bir joyda sanaydi, shuning uchun uni odam ham, dasturiy vosita ham oʻqiy oladi.

Tarixi qisqa: spetsifikatsiya Swagger 2.0 dan chiqqan, SmartBear uni 2015 yilda topshirgan, 2016 yilda u alohida loyihaga aylangan, boshqaruvi esa Linux Foundation huzuridagi ochiq tuzilmada. Versiyalar haqida ikki sahifa kelishmaydi. OpenAPI FAQ sahifasi eng soʻnggi versiyani 3.1.1, yaʼni 2024 yil 24 oktyabr, deydi. Spetsifikatsiyaning “latest” sahifasi esa 2026 yil 10 sentyabr sanali 3.2.1 versiyasini koʻrsatadi, versiyalar roʻyxatida 3.2.0 ham bor. FAQ sahifasi yangilanmay qolganga oʻxshaydi, lekin sahifa yangilanish sanasini bermaydi.

OpenAPI hujjati xizmat nima qilishini tasvirlaydi, lekin uning oʻzi xizmat ishlashini taʼminlamaydi. Hujjat va real xatti-harakat orasida tafovut boʻlishi mumkin, shu sababli integratsiya sinov muhitida real javoblar bilan solishtirib tekshiriladi. Bu tahririyat xulosasi, spetsifikatsiya matnidan olingan daʼvo emas.

API va REST bir narsa emas

“REST API” iborasi keng tarqalgan, lekin har bir veb API REST emas.

Veb-API larni koʻpincha “REST API” deb ataydilar. REST esa Roy Fielding 2000 yilda UC Irvine dissertatsiyasida tasvirlagan arxitektura uslubi: dissertatsiya uni Web arxitekturasini loyihalash tajribasidan chiqargan. HTTP orqali ishlaydigan har bir API ham shu uslubga mos kelavermaydi. Farq alohida maqolaning mavzusi.

Bundan nima kelib chiqadi

Quyidagi xulosa tahririyatniki. Hamkor yoki dasturchi “API bor” desa, toʻrtta narsani aniqlab olish kerak:

1. qaysi amallar ochiq: oʻqish, yozish yoki oʻchirish.
2. murojaat qaysi kalit bilan va kimning nomidan qilinadi.
3. xato holatida qanday kod va tana qaytadi.
4. API qaysi versiyaga bogʻlangan va bu versiya qachongacha ishlaydi.

Yana bir savol birinchi toʻrttadan keyin turadi: soʻrov qayta yuborilsa nima boʻladi. Yuqorida koʻrilganidek, usul idempotent boʻlsa qayta yuborish xavfsizroq, boʻlmasa ikki nusxa yaratilishi mumkin. Integratsiyaning yaxshi yoki yomon yozilganligi koʻpincha shu javobdan bilinadi: tarmoq har doim ham uzluksiz ishlamaydi, shuning uchun uzilishga tayyor kod kerak.

Oxirgi band bejiz emas. Odoo 20 hujjatiga koʻra, eski XML-RPC va JSON-RPC interfeyslarining umumiy va obyekt xizmatlari Odoo 22 da, yaʼni 2028 yil kuzida, olib tashlanishi rejalashtirilgan. Odoo Online uchun bu 21.1 versiyasi, yaʼni 2027 yil qishi. Maʼlumotlar bazasi xizmati esa Odoo 20 da, yaʼni 2026 yil kuzida, allaqachon olib tashlangan. Odoo 19 hujjati ham shu rejani eslatadi va yangi JSON-2 interfeysiga oʻtishni koʻrsatadi. Oʻz kodini eski interfeysga bogʻlagan integratsiya shu sanalardan oldin qayta yozilishi kerak.

API ikki dastur orasidagi shartnoma, shartnomaning esa muddati va versiyasi boʻladi. Bir tomonning dasturi yangilansa, ikkinchi tomonning integratsiyasi buzilishi mumkin: bu texnik xato emas, kelishuv shartining oʻzgarishi.