REST API Loyihalashda Best Practice: 7 Ta Oltin Qoida

Zamonaviy dasturlashda deyarli barcha veb va mobil ilovalar backend bilan API (Application Programming Interface) orqali muloqot qiladi. Ayniqsa, frontend va backend alohida arxitekturada (masalan, React va Django REST Framework yoki FastAPI) ishlayotgan paytda to'g'ri loyihalangan REST API loyihaning asosi hisoblanadi.

Noto'g'ri tuzilgan endpointlar, tushunarsiz status kodlari va noaniq ma'lumotlar tuzilishi jamoada tushunmovchiliklarga, frontendchi va backendchi o'rtasidagi ortiqcha bahslarga sabab bo'ladi. Ushbu maqolada amaliyotda sinalgan va professional loyihalarda qat'iy rioya qilinadigan 7 ta eng muhim REST API best practice qoidalarini ko'rib chiqamiz.

1. Otlardan (Nouns) Foydalaning, Fe'llardan Voz Keching

Ko'plab boshlang'ich dasturchilar endpoint nomlariga harakatni bildiruvchi so'zlarni (fe'llarni) qo'shib yuborishadi. Masalan: /api/get-users, /api/create-user yoki /api/delete-user/12. Bu REST falsafasiga butunlay ziddir.

REST arxitekturasida URL faqat resursni ifodalashi lozim, harakatni esa standart HTTP metodlari (GET, POST, PUT, PATCH, DELETE) belgilaydi:

• GET /api/v1/articles — Maqolalar ro'yxatini olish;
• POST /api/v1/articles — Yangi maqola yaratish;
• GET /api/v1/articles/42 — ID raqami 42 bo'lgan maqolani olish;
• PUT /api/v1/articles/42 — Maqolani to'liq yangilash;
• PATCH /api/v1/articles/42 — Maqolaning faqat ayrim maydonlarini qisman yangilash;
• DELETE /api/v1/articles/42 — Maqolani o'chirish.

Resurs nomlari har doim ko'plikda (plural) bo'lishi qabul qilingan standart hisoblanadi (masalan, /users, /orders, /products).

2. HTTP Status Kodlaridan To'g'ri Foydalaning

Eng keng tarqalgan xatolardan biri — har qanday holatda, hatto tizimda xatolik yuz berganda ham 200 OK qaytarib, javob ichida {"error": true, "message": "Not found"} yuborishdir. Bu frontenddagi so'rov kutubxonalarini (masalan, Axios, TanStack Query) chalg'itadi.

Asosiy status kodlarining to'g'ri qo'llanilishi:

• 200 OK — Muvaffaqiyatli GET, PUT yoki PATCH so'rovlari uchun;
• 201 Created — Yangi obyekt muvaffaqiyatli yaratilganda (POST);
• 204 No Content — Resurs muvaffaqiyatli o'chirilganda va javob tanasi bo'sh bo'lganda (DELETE);
• 400 Bad Request — Foydalanuvchi yuborgan ma'lumotlar validatsiyadan o'tmaganda;
• 401 Unauthorized — Foydalanuvchi tizimga kirmagan yoki token muddati o'tgan;
• 403 Forbidden — Foydalanuvchi tizimga kirgan, lekin bu amalni bajarishga ruxsati yo'q;
• 404 Not Found — So'ralgan resurs mavjud emas;
• 429 Too Many Requests — So'rovlar chegarasi oshib ketganda (Rate Limiting);
• 500 Internal Server Error — Server ichidagi kutilmagan dasturiy xato.

3. API Versiyalashni Dastlabki Kundanoq Yo'lga Qo'ying

Loyihalar doimo o'zgaradi va kengayadi. Kelajakda API ma'lumotlar tuzilmasini o'zgartirishingizga to'g'ri kelganda, bu eski mobil ilovalar yoki mijozlar dasturini ishdan chiqarishi mumkin. Bunga breaking change deyiladi.

Shu sababli, API yaratishni boshidanoq URL yo'liga versiyani qo'shing:

https://api.pycoder.uz/v1/users
https://api.pycoder.uz/v2/users

Versiyalash yordamida eski ilovalar v1 bilan bemalol ishlashda davom etadi, yangi imkoniyatlar esa v2 da ishlab chiqiladi.

4. Standartlashtirilgan Xatolik Javoblari Formatini Yarating

Frontend dasturchi yoki mobil dasturchi har bir endpointdagi xatolarni alohida usulda ushlashga majbur bo'lmasligi kerak. Tizimdagi barcha xatoliklar bir xil JSON qolipida qaytishi shart.

Misol uchun:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Kiritilgan ma'lumotlar yaroqsiz",
    "details": [
      {
        "field": "email",
        "message": "Email manzili to'g'ri formatda kiritilmadi"
      }
    ]
  }
}

Bunday aniq va standart format frontendchiga foydalanuvchi interfeysida xatolik haqida chiroyli xabar chiqarishga imkon beradi.

5. Paginatsiya, Filtrlash va Saralashni To'g'ri Tashkil Qiling

Agar bazada 10 000 ta mahsulot bo'lsa, GET /api/v1/products so'rovi barcha yozuvlarni birdaniga qaytarmasligi kerak. Bu server resurslarini haddan ortiq band qiladi va javob qaytish vaqtini cho'zadi.

So'rov parametrlaridan (Query Parameters) to'g'ri foydalaning:

• Paginatsiya: /api/v1/products?page=2&limit=20 (yoki cursor usuli);
• Filtrlash: /api/v1/products?category=smartphones&in_stock=true;
• Saralash: /api/v1/products?sort=-price (minus belgisi kamayish tartibida saralashni bildiradi);
• Qidiruv: /api/v1/products?search=iphone.

6. Xavfsizlik va Rate Limiting Sozlamalari

Har qanday ochiq API ruxsatsiz kirishlardan va bot hujumlaridan himoyalangan bo'lishi lozim:

• HTTPS: Barcha so'rovlar faqat shifrlangan SSL/TLS protokoli orqali qabul qilinishi shart;
• Avtorizatsiya: Zamonaviy tizimlarda Authorization: Bearer <token> sarlavhasi (JWT yoki xavfsiz sessiya tokeni) orqali tekshiruv yo'lga qo'yiladi;
• Rate Limiting (Throttling): Bitta IP yoki bitta foydalanuvchiga daqiqasiga masalan 60 tadan ortiq so'rov yuborishni cheklang. Bu serverni DDoS hujumlaridan va resurslarni o'g'irlashdan saqlaydi;
• CORS: Faqat siz ruxsat bergan frontend domenlari API ga murojaat qila olishini ta'minlang.

7. API Hujjatlashtirish (Swagger va OpenAPI)

Hujjatlashtirilmagan API — bu mavjud bo'lmagan API bilan tengdir. Frontendchi yoki uchinchi tomon integratsiyasi har bir parametrni bilish uchun sizga doimiy yozib turmasligi lozim.

Django REST Framework (drf-spectacular), FastAPI yoki Node.js bilan ishlayotganda OpenAPI standartidagi avtomatik Swagger/Redoc sahifalarini ulang. Hujjatda har bir endpoint uchun talab qilinadigan parametrlar, sarlavhalar va javob namunasi aniq aks etishi lozim.

Xulosa

Toza, tushunarli va xavfsiz REST API yaratish dasturchining professional mahoratini ko'rsatadigan eng muhim omillardan biridir. Ushbu 7 ta qoidaga rioya qilish orqali siz jamoangiz bilan ishlashni yengillashtirasiz, loyihangizni masshtablanishga tayyorlaysiz va xatolarni minimumga tushirasiz.