API endpoint: nima u va so‘rovlar tavsifini qanday o‘qish

Endpoint — API’ning aniq bir «kirish nuqtasi»: so‘rov yuboriladigan manzil va u bilan bajariladigan amal. Agar API — muassasa bo‘lsa, endpointlar uning alohida xonalari: har biri o‘z ishini bajaradi.

Endpoint tarkibi

Odatda endpoint ikki qismdan iborat:

• HTTP metodi — nima qilish: GET (olish), POST (yaratish), PUT/PATCH (o‘zgartirish), DELETE (o‘chirish);
• yo‘l — qaysi resurs bilan: /orders, /orders/{id}, /customers/{id}/payments.

Masalan, «GET /orders/{id}» — buyurtma ma’lumotlarini olish, «POST /orders» — yangi buyurtma yaratish. Bir xil yo‘l turli metodlar bilan turli endpoint hisoblanadi.

To‘liq manzil asosiy manzil va yo‘ldan iborat: https://api.misol.uz/v1/orders/123.

Parametrlar turlari

Yo‘l parametrlari. Manzil ichida: /orders/{id} — {id} o‘rniga buyurtma raqami.

So‘rov parametrlari. Manzil oxirida, ? belgisidan keyin: /orders?status=paid&page=2. Odatda filtrlash, saralash va sahifalash uchun.

Sarlavhalar. So‘rov bilan birga yuboriladigan xizmat ma’lumotlari: avtorizatsiya tokeni, ma’lumot formati, til.

So‘rov tanasi. POST va PUT so‘rovlarida yuboriladigan ma’lumot, odatda JSON: yangi buyurtma tarkibi, mijoz ma’lumotlari.

Endpoint tavsifini o‘qish: misol

Hujjatda shunday yozilgan bo‘lishi mumkin:

• POST /v1/orders — yangi buyurtma yaratadi
• Sarlavha: Authorization — Bearer token
• Tana: customer_id (raqam, majburiy), items (ro‘yxat, majburiy), comment (matn, ixtiyoriy)
• Javob 201: yaratilgan buyurtma, id va status bilan
• Xato 400: majburiy maydon yo‘q yoki noto‘g‘ri
• Xato 404: mijoz topilmadi

Bundan tushunamiz: buyurtma yaratish uchun token, mijoz raqami va mahsulotlar ro‘yxati kerak; muvaffaqiyatli bo‘lsa, buyurtma raqami qaytadi.

Versiya

Yo‘ldagi /v1/ — API versiyasi. Yangi, mos kelmaydigan o‘zgarishlar /v2/ da chiqariladi, eski integratsiyalar esa /v1/ da ishlashda davom etadi. Versiyalash eski integratsiyalarni kutilmagan buzilishdan himoya qiladi.

Endpointlarni nomlash qoidalari

Yaxshi API’da endpointlar oldindan aytib bo‘ladigan bo‘ladi:

• ot so‘zlar, fe’llar emas: /orders, /createOrder emas;
• ko‘plik shaklida to‘plamlar;
• ichma-ich resurslar mantiqiy: /customers/{id}/orders;
• yagona uslub: hamma joyda kichik harflar va bir xil ajratuvchilar.

Buyurtmachi uchun foydasi

Endpoint tavsifini o‘qiy olish quyidagilarda yordam beradi:

• texnik vazifada aniq yozish: «tizim buyurtma holatini olish uchun endpoint taqdim etishi kerak»;
• pudratchi yuborgan API hujjatini tushunish va bo‘shliqlarni ko‘rish;
• integratsiya xatosini muhokama qilishda — qaysi endpoint, qanday so‘rov, qanday javob.

Endpointni sinab ko‘rish

Hujjatda «Try it» tugmasi bo‘lsa, so‘rovni brauzerdan yuborib ko‘rish mumkin. Bo‘lmasa — Postman kabi vositalar. Sinovni har doim sinov muhitida va sinov kaliti bilan o‘tkazing.