API hujjatlari: integratsiya tez o‘tishi uchun nima bo‘lishi kerak

API hujjatlari — dasturchi uchun yo‘riqnoma: API bilan qanday ulanish, qanday so‘rov yuborish va qanday javob kutish. Yaxshi hujjat bilan dasturchi integratsiyani mustaqil quradi. Yomon hujjat bilan har bir qadam savol-javob, taxmin va xatolar orqali o‘tadi.

Boshlash bo‘limi

• API nima qiladi va kimlar uchun — bir-ikki jumla
• Asosiy manzil (base URL): sinov va ishchi muhit uchun
• Kirish olish tartibi: ro‘yxatdan o‘tish, kalit olish, shartnoma kerakmi
• Birinchi so‘rov misoli — bir necha daqiqada ishlaydigan

Avtorizatsiya

Kalit yoki token qanday olinadi, so‘rovga qayerga qo‘yiladi (sarlavha, parametr), muddati, yangilash tartibi. Misollar bilan. Imzo talab qilinsa — algoritm qadamma-qadam va tekshirish uchun namunaviy qiymatlar.

Metodlar ro‘yxati

Har bir metod uchun:

• manzil va HTTP metodi;
• vazifasi — bir jumla;
• parametrlar: nomi, turi, majburiymi, ruxsat etilgan qiymatlar, misol;
• so‘rov tanasi misoli;
• muvaffaqiyatli javob misoli va har bir maydon tavsifi;
• mumkin bo‘lgan xatolar.

Misollar haqiqiy ishlaydigan bo‘lishi kerak — nusxa olib, ishga tushirish mumkin.

Xatolar

Barcha xato kodlari jadvali: kod, ma’nosi, sababi, nima qilish kerak. Masalan: «Buyurtma allaqachon to‘langan — qayta to‘lov yaratmang, holatni tekshiring». Xatolar formati yagona bo‘lishi kerak.

Limitlar va qoidalar

• So‘rovlar chegarasi va undan oshganda nima bo‘ladi
• Sahifalash: sahifa hajmi, keyingi sahifani olish
• Sana va vaqt formati, vaqt zonasi
• Valyuta va summalar formati — tiyin yoki so‘mda
• Matnlar kodirovkasi

Summalar birligi bo‘yicha noaniqlik integratsiyadagi eng xavfli xatolardan biri.

Vebhuklar bo‘lsa, ular uchun ham alohida tavsif kerak: qanday hodisalar yuboriladi, xabar formati, imzoni tekshirish, qayta yuborish qoidalari, sizning serveringiz qanday javob qaytarishi kerak.

Sinov muhiti

Sinov kalitlari, sinov kartalari yoki ma’lumotlari, muayyan xato holatlarini qanday sinash mumkin. Sinov muhiti bo‘lmasa, integratsiya ishchi ma’lumotlarda sinaladi — bu xavfli.

Mashina o‘qiydigan tavsif

OpenAPI (Swagger) formatidagi tavsif hujjatlarni avtomatik ko‘rsatish, testlar yaratish va mijoz kodini generatsiya qilish imkonini beradi. U odam uchun yozilgan matnli tushuntirishlarni almashtirmaydi, balki ularni to‘ldiradi.

O‘zgarishlar jurnali va versiyalar

• API versiyasi va qaysi versiya joriy
• Har bir o‘zgarish sanasi va tavsifi
• Eskirgan metodlar va ular qachon o‘chiriladi
• Moslikni buzadigan o‘zgarishlar haqida oldindan ogohlantirish

Hujjat sifatini tekshirish

Yangi dasturchiga faqat hujjat berib, oddiy integratsiyani — masalan, buyurtma yaratish va holatini olishni — qilishni so‘rang. Uning har bir savoli hujjatdagi bo‘shliqni ko‘rsatadi. Agar siz API buyurtma qilayotgan bo‘lsangiz, hujjatlarni ish natijasining majburiy qismi sifatida shartnomaga kiriting.