API dizayn qo'llanmasi

Yaxshi API — bashoratli, izchil, hujjatlangan. Buni bir marta to'g'ri qil — minglab dasturchi (va kelajakdagi sen) rahmat aytadi. 5.7 va 13.6-boblarga tayanadi.

1. REST tamoyillari

• Resurs — ot, URL'da (/users, /orders/5) — fe'l emas (/getUsers ).
• HTTP metodi amalni bildiradi:

GET    /users        — ro'yxat
GET    /users/5      — bitta
POST   /users        — yaratish
PUT    /users/5      — to'liq almashtirish
PATCH  /users/5      — qisman yangilash
DELETE /users/5      — o'chirish

• Ichma-ich resurs: /users/5/orders (5-foydalanuvchi buyurtmalari).
• Stateless — har so'rov mustaqil (server sessiya saqlamaydi; token bilan).

2. Status kodlar (to'g'ri ishlat)

200 OK              — muvaffaqiyat (GET, PUT, PATCH)
201 Created         — yaratildi (POST)
204 No Content      — muvaffaqiyat, javob tanasi yo'q (DELETE)
400 Bad Request     — noto'g'ri so'rov (validatsiya)
401 Unauthorized    — kirish yo'q (login kerak)
403 Forbidden       — ruxsat yo'q (login bor, lekin huquq yo'q)
404 Not Found       — topilmadi
409 Conflict        — to'qnashuv (takror email)
422 Unprocessable   — validatsiya xatosi (ba'zi API'lar)
429 Too Many        — rate limit
500 Server Error    — server xatosi

Har doim to'g'ri kod qaytar — 200 ichida {error: true} qaytarish (mijoz status'ga ishonadi).

3. So'rov va javob formati

Izchil JSON struktura. Javob konventsiyasini tanla va saqla:

// Muvaffaqiyat
{ "data": { "id": 5, "name": "Ali" } }

// Ro'yxat + metadata
{ "data": [...], "meta": { "total": 100, "page": 1, "perPage": 20 } }

// Xato (izchil format)
{ "error": { "code": "VALIDATION_ERROR", "message": "Email noto'g'ri",
             "fields": { "email": "Yaroqsiz format" } } }

• camelCase yoki snake_case — birini tanla, hamma joyda saqla.
• Sana — ISO 8601 (2026-06-23T10:00:00Z), doim UTC.
• Pul — eng kichik birlik, butun son (0.1-bob).

4. Pagination (sahifalash)

OFFSET (oddiy):   GET /users?page=2&limit=20
   oson    katta offset sekin, ma'lumot siljisa dublikat

CURSOR (yaxshi):  GET /users?cursor=eyJpZCI6MTAwfQ&limit=20
   barqaror, tez (katta ma'lumot)    "N-sahifaga sakrash" yo'q

Javobda nextCursor yoki meta.total/page qaytar.

5. Filtrlash, saralash, qidiruv

GET /products?category=phone&minPrice=100&sort=-price&q=samsung
              └ filtr ──────────────────┘ └ saralash ┘ └ qidiruv

• sort=-price — minus = kamayish bo'yicha.
• Filtr nomlari izchil; validatsiya qil (injection — 14.3).

6. Versiyalash (versioning)

API o'zgaradi, eski mijozlar buzilmasligi kerak:

URL'da:     /v1/users   /v2/users     (eng keng, ko'rinarli)
Header'da:  Accept: application/vnd.api.v2+json

• Buzuvchi o'zgarishda yangi versiya (maydon olib tashlash, format o'zgartirish).
• Eski versiyani bir muddat qo'llab-quvvatla (deprecation muddat ber).

7. Autentifikatsiya va xavfsizlik

• Token (JWT/Bearer): Authorization: Bearer <token> 14.6-bob.
• HTTPS majburiy 14.7-bob.
• Rate limiting 14.8-bob + 429 + Retry-After header.
• Kirishni validatsiya qil — har maydonni 14.3-bob.
• CORS to'g'ri sozla (kerakli origin) 14.7-bob.
• Maxfiy ma'lumotni qaytarma (parol hash, ichki ID).

8. Idempotentlik

• GET, PUT, DELETE — idempotent (takror bajarsa natija bir xil).
• POST — idempotent emas (har safar yangi yaratadi). To'lovda Idempotency-Key header bilan takror oldini ol.

9. Xato boshqaruvi

• Aniq, foydali xabar — "Email noto'g'ri" ("Xatolik" emas).
• Maydon bo'yicha xato (forma uchun): qaysi maydon, nima muammo.
• Ichki xatoni yashir — 500da stack trace qaytarma (xavfsizlik), log'ga yoz.
• Izchil format — hamma xato bir xil tuzilishda (3-bo'lim).

10. Hujjatlash (OpenAPI/Swagger)

• OpenAPI (Swagger) — API'ni standart formatda tasvirla interaktiv hujjat avtomatik.
• NestJS — @nestjs/swagger (8-QISM) avtomatik generatsiya qiladi.
• Har endpoint: tavsif, parametrlar, so'rov/javob namunasi, status kodlar.

// NestJS Swagger misol
@ApiOperation({ summary: "Foydalanuvchi yaratish" })
@ApiResponse({ status: 201, description: "Yaratildi" })
@Post()
create(@Body() dto: CreateUserDto) { ... }

REST vs alternativalar

API checklist

• Resurs-asosli URL (ot, fe'l emas)
• To'g'ri HTTP metod va status kod
• Izchil JSON format (data/error/meta)
• Pagination, filtr, saralash
• Validatsiya + aniq xato xabari
• Auth + HTTPS + rate limit
• Versiyalash strategiyasi
• OpenAPI hujjat
• Idempotentlik (kerakli joyda)

Bog'liq: 5.7 REST, 13.6 · Bosh sahifa: README.