7-ma’ruza matni · Korxona ilovalarini dasturlash
Resurslar va HTTP · API Resource · versiya va sahifalash · xatolar formati · JWT · OpenAPI
Omborchining mobil ilovasi, 1C buxgalteriyasi va Telegram-bot OmborPro dan bir xil ma’lumotni qanday oladi? Hozircha javob bermang. Brauzer uchun yozilgan Blade sahifalari bu mijozlarga yetarlimi — o‘ylab ko‘ring.
Barcha mijozlar uchun yagona shartnoma — REST API kerak: resurslar (/api/v1/products), standart HTTP metodlari va status kodlari, JSON ko‘rinishi, yagona xato formati va token (JWT) orqali autentifikatsiya. Shartnoma OpenAPI hujjatida yoziladi.
/api/v1 resurslar daraxti, sahifalash va filtrlash parametrlariniRoute::apiResource, API Resource va Form Request niper_page, ma’lumot sizib chiqishiResurs va URI · metodlar: xavfsiz va idempotent · status kodlar · sarlavhalar
REST (Representational State Transfer) — Roy Filding 2000 yilda dissertatsiyasida ta’riflagan arxitektura uslubi. Uning asosiy cheklovlari: mijoz–server ajratilgan, har bir so‘rov o‘zi yetarli (stateless — server sessiyada mijoz holatini saqlamaydi), javoblarni keshlash mumkin, interfeys yagona (resurs + standart metodlar), tizim qatlamli (proxy, balanslagich). Amaliyotda “REST API” deganda URI bilan aniqlanadigan resurslar, ular ustida standart HTTP metodlari va JSON ko‘rinishi tushuniladi. Korxona ilovasida API bir nechta mijozga xizmat qiladi: omborchining mobil ilovasi, 1C bilan almashinuv, hamkor do‘konlar, Telegram-bot. Muhimi — API yangi biznes-logika emas: “Biznes-logika va servis qatlami” mavzusidagi OrderService va StockService ni Blade ekranlari ham, API ham bir xil chaqiradi.
Resurs — biznes obyekti yoki ularning to‘plami: mahsulot, buyurtma, hisob-faktura. URI da ot ishlatiladi, ko‘plikda: /api/v1/products, /api/v1/products/15, /api/v1/orders/42/items. Fe’l URI ga yozilmaydi — /getProducts, /createOrder noto‘g‘ri, chunki amalni HTTP metodi bildiradi. CRUD ga sig‘maydigan biznes-amallar (tasdiqlash, rezerv, bekor qilish) uchun ikki yo‘l bor: POST /orders/42/confirm kabi alohida amal-endpoint yoki PATCH /orders/42 bilan holatni o‘zgartirish. OmborPro da birinchisini tanlaymiz: har bir o‘tish holat mashinasi va invariantlarni tekshiradigan aniq servis metodiga mos keladi, hujjatlashtirish va ruxsat berish ham osonlashadi.
HTTP metodlarining ikki muhim xossasi bor. Xavfsiz (safe) metod server holatini o‘zgartirmaydi: GET, HEAD. Idempotent metodni bir marta yoki o‘n marta yuborish natijasi bir xil: GET, PUT, DELETE. POST idempotent emas — mobil tarmoq uzilib, ilova POST /orders ni qayta yuborsa, ikkita buyurtma yaratiladi. Shuning uchun to‘lov va buyurtma yaratishda mijoz Idempotency-Key sarlavhasini yuboradi, server esa shu kalit bilan kelgan takroriy so‘rovga avvalgi javobni qaytaradi. PUT resursni to‘liq almashtiradi, PATCH — qisman o‘zgartiradi; Laravel apiResource ikkalasini ham update metodiga yo‘naltiradi.
Status kod — mijoz uchun eng muhim signal. 200 OK — muvaffaqiyat, 201 Created — yangi resurs (Location sarlavhasi bilan), 204 No Content — tanasiz muvaffaqiyat (o‘chirish). 401 — token yo‘q yoki yaroqsiz, 403 — token bor, lekin ruxsat yo‘q (omborchi hisob-fakturalarni ko‘rmoqchi), 404 — resurs topilmadi, 409 Conflict — biznes-qoida to‘qnashuvi (qoldiq yetarli emas, shipped buyurtmani bekor qilish), 422 — validatsiya xatosi (Laravel standarti), 429 — so‘rovlar limiti oshdi, 500 — server xatosi. Keng tarqalgan xato — har doim 200 qaytarib, tanada {"success": false} yozish: mijoz, monitoring va kesh muvaffaqiyatsizlikni ajrata olmaydi.
Sarlavhalar ham shartnoma qismi. Accept: application/json — mijoz JSON kutadi; Laravel da bu ayniqsa muhim: usiz validatsiya xatosida 422 JSON o‘rniga oldingi sahifaga 302 redirect qaytishi mumkin. Content-Type: application/json — so‘rov tanasi formati, Authorization: Bearer <token> — autentifikatsiya, Location — yaratilgan resurs manzili, Retry-After — 429 dan keyin qancha kutish kerak. Sana va vaqt ISO 8601 da (2026-10-20T09:15:00+05:00), pul esa satr ko‘rinishidagi aniq o‘nli son ("385000.00") bo‘lib uzatiladi — JSON dagi float aniqlikni yo‘qotishi mumkin.
REST API — resurslar ustida standart HTTP metodlari bilan ishlash shartnomasi. URI — ot, metod — fe’l.
products, orders/42, orders/42/items.Authorization sarlavhasida keladi.POST /api/v1/orders/42/confirm./api/getProducts, /api/order/delete/42 — URI da fe’l. ✓ GET /api/v1/products, DELETE /api/v1/orders/42.| Metod | OmborPro misoli | Xavfsiz | Idempotent |
|---|---|---|---|
GET | GET /products?page=2 — ro‘yxat | ha | ha |
POST | POST /orders — yangi buyurtma | yo‘q | yo‘q |
PUT | PUT /products/15 — to‘liq almashtirish | yo‘q | ha |
PATCH | PATCH /products/15 — narxni o‘zgartirish | yo‘q | kafolatlanmaydi |
DELETE | DELETE /products/15 — soft delete | yo‘q | ha |
POST (amal) | POST /orders/42/confirm — holat o‘tishi | yo‘q | yo‘q |
POST ni xavfsiz takrorlash uchun Idempotency-Key sarlavhasi: server shu kalit bilan birinchi javobni saqlab, takroriy so‘rovga qaytaradi.| Kod | Ma’nosi | OmborPro misoli |
|---|---|---|
200 OK | muvaffaqiyat, tanada natija | mahsulotlar ro‘yxati |
201 Created | yangi resurs + Location | buyurtma yaratildi |
204 No Content | muvaffaqiyat, tana yo‘q | mahsulot o‘chirildi |
401 Unauthorized | token yo‘q yoki muddati o‘tgan | exp o‘tib ketgan JWT |
403 Forbidden | token bor, ruxsat yo‘q | omborchi hisob-fakturani so‘radi |
404 Not Found | resurs topilmadi | /products/9999 |
409 Conflict | biznes-qoida to‘qnashuvi | rezerv uchun qoldiq yetarli emas |
422 Unprocessable | validatsiya xatosi | sku band, price manfiy |
400 — buzuq JSON, 429 — limit oshdi (Retry-After), 500 — kutilmagan server xatosi.Har bir vaziyat uchun eng to‘g‘ri HTTP javob kodini tanlang.
POST /api/v1/orders muvaffaqiyatli, yangi buyurtma yaratildi.✓ 201 — Yangi resurs yaratilganda 201 Created va Location sarlavhasi qaytariladi.
UN-001 dan 5 dona kerak, mavjud qoldiq 3.✓ 409 — So‘rov to‘g‘ri tuzilgan, lekin biznes-holat bilan to‘qnashadi — 409 Conflict.
GET /api/v1/invoices so‘raldi; token yaroqli.✓ 403 — Foydalanuvchi aniqlangan, lekin ruxsati yo‘q — 403 Forbidden.
price maydoni -500 bo‘lib keldi.✓ 422 — Maydon qiymati qoidaga zid — validatsiya xatosi, Laravel 422 qaytaradi.
/api/createOrder yaxshi URI emas?URI da fe’l bor; amalni HTTP metodi bildiradi: POST /api/v1/orders.
POST va PUT ning idempotentlik bo‘yicha farqi nimada?PUT ni takrorlash natijasi bir xil (idempotent), POST ni takrorlash yangi resurs yaratadi.
401 — foydalanuvchi aniqlanmadi (token yo‘q/yaroqsiz); 403 — aniqlandi, lekin ruxsati yo‘q.
install:api · Route::apiResource · ingichka controller · JsonResource · 201 va Location
Laravel 12 skeletida routes/api.php fayli standart holda yo‘q — u php artisan install:api buyrug‘i bilan qo‘shiladi. Buyruq faylni yaratadi, bootstrap/app.php dagi withRouting() ga api: marshrutlarini ulaydi va Sanctum paketini o‘rnatadi. Bu fayldagi barcha marshrutlar avtomatik /api prefiksi va api middleware guruhini oladi (sessiya va CSRF yo‘q). Versiya uchun ichida Route::prefix('v1')->name('v1.') guruhini ochamiz, controllerlarni esa App\Http\Controllers\Api\V1 papkasiga joylaymiz — v2 paydo bo‘lganda eski kod tegmasdan qoladi.
Route::apiResource('products', ProductController::class) beshta marshrut yaratadi: index (GET ro‘yxat), store (POST), show (GET bitta), update (PUT/PATCH), destroy (DELETE). Oddiy Route::resource dan farqi — HTML formalar uchun create va edit yo‘q. Route model binding {product} parametrini Product modeliga aylantiradi; topilmasa 404 avtomatik. php artisan route:list --path=api bilan natijani tekshirish odat bo‘lsin.
Controller ingichka bo‘lishi kerak: so‘rovni qabul qiladi, validatsiyani Form Request ga, biznes-amalni servisga, javob shaklini API Resource ga topshiradi. 6-mavzudagi StoreProductRequest ni API da ham qayta ishlatamiz: agar so‘rovda Accept: application/json bo‘lsa, validatsiya xatosi 422 va {"message": ..., "errors": {"sku": [...]}} ko‘rinishida qaytadi. Model ma’lumotlari $request->validated() orqali olinadi — $request->all() emas, aks holda mijoz is_active yoki boshqa ruxsatsiz maydonni ham yuborib qo‘yishi mumkin.
API Resource (JsonResource) — model bilan JSON o‘rtasidagi o‘zgartirish qatlami. Modelni to‘g‘ridan-to‘g‘ri qaytarish xavfli: jadvalga ustun qo‘shilsa, u API ga “sizib” chiqadi (masalan, users.password xeshi), ustun nomi o‘zgarsa mijoz buziladi. Resource da maydonlar qo‘lda tanlanadi, sana ISO 8601 ga o‘giriladi, bog‘liq modellar faqat yuklangan bo‘lsa qo‘shiladi ($this->whenLoaded('category')), shartli maydonlar $this->when(...) bilan beriladi. ProductResource::collection($paginator) sahifalash ma’lumotlarini (links, meta) ham avtomatik qo‘shadi.
Yaratilgan resurs uchun 201 Created kerak. Laravel buni o‘zi biladi: Resource ichidagi model wasRecentlyCreated bo‘lsa, javob statusi avtomatik 201 bo‘ladi. Location sarlavhasini esa o‘zimiz qo‘shamiz: (new ProductResource($product))->response()->header('Location', ...). O‘chirishdan keyin response()->noContent() — 204. Mahsulotlar deleted_at bilan soft delete qilinadi (3-mavzu), shuning uchun DELETE hujjatlarda ishlatilgan mahsulotni yo‘qotmaydi, faqat katalogdan yashiradi.
use App\Http\Controllers\Api\V1\AuthController; use App\Http\Controllers\Api\V1\OrderController; use App\Http\Controllers\Api\V1\ProductController; use Illuminate\Support\Facades\Route; Route::prefix('v1')->name('v1.')->group(function () { Route::post('auth/login', [AuthController::class, 'login']) ->middleware('throttle:5,1'); Route::middleware(['auth:api', 'throttle:api'])->group(function () { Route::apiResource('products', ProductController::class); Route::apiResource('orders', OrderController::class) ->only(['index', 'store', 'show']); Route::post('orders/{order}/confirm', [OrderController::class, 'confirm']); }); });
$ php artisan route:list --path=api/v1
POST api/v1/auth/login ........ Api\V1\AuthController@login
GET|HEAD api/v1/products ......... v1.products.index
POST api/v1/products ......... v1.products.store
GET|HEAD api/v1/products/{product} v1.products.show
POST api/v1/orders/{order}/confirmprefix('v1') — /api + /v1 — URL da versiya; nomlar v1.products.indexthrottle:5,1 — login uchun daqiqasiga 5 urinish — parol tanlashdan himoyaauth:api — api guard (JWT) — tokensiz so‘rov 401 oladicreate/edit yo‘qorders/{order}/confirm — CRUD dan tashqari biznes-amal, OrderService ni chaqiradiclass ProductController extends Controller { public function index(Request $request) { $perPage = min(max($request->integer('per_page', 20), 1), 100); $products = Product::with('category')->orderBy('name') ->paginate($perPage)->withQueryString(); return ProductResource::collection($products); } public function store(StoreProductRequest $request) { $product = Product::create($request->validated()); return (new ProductResource($product)) ->response() // model yangi — status 201 ->header('Location', route('v1.products.show', $product)); } }
GET /api/v1/products?per_page=500 → 200, per_page 100 ga cheklandi
POST /api/v1/products (sku band) → 422 {"errors": {"sku": [...]}}
POST /api/v1/products (to‘g‘ri) → 201, Location: .../products/16min(max(..., 1), 100) — per_page chegarasi — 1 000 000 yozuvli javobdan himoyawith('category') — eager loading — Resource ichida N+1 bo‘lmaydiwithQueryString() — filtrlar links.next ichida saqlanadi$request->validated() — faqat qoidalardan o‘tgan maydonlar->response()->header() — 201 avtomatik, Location ni biz qo‘shamizclass ProductResource extends JsonResource { public function toArray(Request $request): array { return [ 'id' => $this->id, 'sku' => $this->sku, 'name' => $this->name, 'unit' => $this->unit, 'price' => $this->price, // decimal:2 → "385000.00" 'is_active' => $this->is_active, 'category' => new CategoryResource( $this->whenLoaded('category')), 'created_at' => $this->created_at?->toIso8601String(), 'links' => ['self' => route('v1.products.show', $this->id)], ]; } }
{"data": {"id": 15, "sku": "UN-001", "name": "Un oliy nav, 50 kg",
"unit": "dona", "price": "385000.00", "is_active": true,
"category": {"id": 3, "name": "Un mahsulotlari"},
"created_at": "2026-10-20T09:15:00+05:00",
"links": {"self": "https://omborpro.test/api/v1/products/15"}}}toArray() — maydonlar qo‘lda tanlanadi — deleted_at, ichki ustunlar chiqmaydi'price' => $this->price — decimal:2 cast satr qaytaradi — float yo‘qwhenLoaded('category') — relation yuklanmagan bo‘lsa, kalit umuman chiqmayditoIso8601String() — sana vaqt zonasi bilan (Asia/Tashkent, +05:00){"data": ...} — Resource javobni standart holda data ichiga o‘raydiPOST /api/v1/products HTTP/1.1 Host: omborpro.test Accept: application/json Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... {"sku": "UN-002", "name": "Un 1-nav, 50 kg", "category_id": 3, "unit": "dona", "price": "355000", "min_stock": 20}
HTTP/1.1 201 Created
Location: https://omborpro.test/api/v1/products/16
Content-Type: application/json
{"data": {"id": 16, "sku": "UN-002", "price": "355000.00", ...}}Accept: application/json — xatolar ham JSON bo‘ladi (aks holda 302 redirect)Authorization: Bearer — har bir so‘rovda token — sessiya yo‘q"price": "355000" — pul satr sifatida — o‘nli aniqlik saqlanadiRoute::apiResource qaysi metodlarni yaratadi va Route::resource dan farqi nimada?index, store, show, update, destroy; HTML formalar uchun create va edit yo‘q.
Maydonlarni nazorat qilish (maxfiy ustunlar chiqmasligi), barqaror shartnoma, format (sana, pul), relationlarni shartli qo‘shish.
Resource dagi model wasRecentlyCreated bo‘lsa, ResourceResponse statusni avtomatik 201 qiladi.
/api/v1 · buzuvchi o‘zgarishlar · offset va cursor · filter va sort · rate limit
API e’lon qilingandan keyin uning mijozlari sizning nazoratingizdan chiqadi: omborchilar telefonidagi ilovani bir oyda yangilaydi, 1C integratsiyasini boshqa jamoa qo‘llab-quvvatlaydi. Shuning uchun buzuvchi o‘zgarish (breaking change) — maydonni o‘chirish yoki qayta nomlash, turini o‘zgartirish (price satrdan songa), majburiy parametr qo‘shish, status kod ma’nosini o‘zgartirish — faqat yangi versiyada qilinadi. Yangi ixtiyoriy maydon, yangi endpoint, yangi ixtiyoriy filtr — buzmaydi va joriy versiyaga qo‘shiladi. Mijozlar esa notanish maydonlarga e’tibor bermasligi kerak (tolerant reader).
Versiyalash usullari: URI da (/api/v1/products) — eng sodda va ko‘rinadigan, loglarda, keshlarda, Postman da darhol ko‘rinadi; sarlavhada (Accept: application/vnd.omborpro.v2+json) — URI toza qoladi, lekin sinash qiyinroq. OmborPro da URI versiyasini tanlaymiz. Eski versiyani o‘chirishdan oldin uni “eskirgan” deb e’lon qilish odat: hujjatda sana yoziladi, javoblarga Sunset sarlavhasi (RFC 8594) qo‘shiladi. Kodda Api/V1 va Api/V2 controllerlari bir xil servis qatlamini chaqiradi, farq faqat Resource va Form Request larda bo‘ladi.
Sahifalash majburiy: GET /products hech qachon butun jadvalni qaytarmasligi kerak. Offset sahifalash (?page=3&per_page=20, Laravel paginate()) jami yozuvlar soni va oxirgi sahifani beradi — jadval ekranlari uchun qulay; lekin katta jadvalda COUNT(*) va OFFSET 200000 qimmat, sahifalar orasida yangi yozuv qo‘shilsa, yozuvlar “siljiydi”. Cursor sahifalash (cursorPaginate()) oxirgi ko‘rilgan kalitdan davom etadi (WHERE id > ?): tez va barqaror, lekin jami son va ixtiyoriy sahifaga sakrash yo‘q. stock_movements jurnali yoki 1C ga sinxronlash uchun cursor, katalog uchun offset mos.
Filtrlash va saralash — query parametrlari: ?category_id=3&is_active=1&sort=-price. Minus belgisi kamayish tartibini bildiradi. Muhim xavfsizlik qoidasi: saralash ustunini foydalanuvchi kiritmasidan to‘g‘ridan-to‘g‘ri orderBy() ga bermang — ruxsat etilgan ro‘yxat (in:name,-name,price,-price) bilan tekshiring. Noma’lum parametr 422 bilan rad etiladi, per_page esa 1–100 oralig‘ida cheklanadi.
Rate limiting — API ni ortiqcha yuklanish va parol tanlashdan himoya qiladi. Laravel da limit AppServiceProvider da RateLimiter::for('api', fn (Request $r) => Limit::perMinute(60)->by($r->user()?->id ?: $r->ip())) bilan aniqlanadi va throttle:api middleware orqali ulanadi. Limit oshsa — 429 Too Many Requests, javobda X-RateLimit-Limit, X-RateLimit-Remaining va Retry-After sarlavhalari bo‘ladi. Login uchun alohida qattiq limit (throttle:5,1) qo‘yiladi.
name → title"price": "385000.00" → 385000warehouse_id endi shart"barcode": nullGET /api/v1/warehouses?is_active=1detail matnini aniqlashtirishSunset: Sat, 01 May 2027 00:00:00 GMT sarlavhasi.<?php function meta(int $total, int $perPage, int $page): array { $empty = $total === 0; return [ 'current_page' => $page, 'from' => $empty ? null : ($page - 1) * $perPage + 1, 'last_page' => max(1, (int) ceil($total / $perPage)), 'to' => $empty ? null : min($page * $perPage, $total), 'total' => $total, ]; } echo json_encode(meta(93, 20, 1)), PHP_EOL; echo json_encode(meta(93, 20, 5)), PHP_EOL; echo json_encode(meta(0, 20, 1)), PHP_EOL;
{"current_page":1,"from":1,"last_page":5,"to":20,"total":93}
{"current_page":5,"from":81,"last_page":5,"to":93,"total":93}
{"current_page":1,"from":null,"last_page":1,"to":null,"total":0}ceil($total / $perPage) — 93 / 20 = 4.65 → 5 sahifamin($page * $perPage, $total) — oxirgi sahifada to = 93, 100 emas$empty ? null — bo‘sh ro‘yxatda from va to — null (Laravel ham shunday)max(1, ...) — bo‘sh ro‘yxatda ham last_page = 1{
"data": [
{"id": 15, "sku": "UN-001", "name": "Un oliy nav, 50 kg"}
],
"links": {
"first": "https://omborpro.test/api/v1/products?page=1",
"last": "https://omborpro.test/api/v1/products?page=5",
"prev": null,
"next": "https://omborpro.test/api/v1/products?page=2"
},
"meta": {
"current_page": 1, "from": 1, "last_page": 5,
"path": "https://omborpro.test/api/v1/products",
"per_page": 20, "to": 20, "total": 93
}
}cursorPaginate() da meta: path, per_page, next_cursor, prev_cursor (total va last_page yo‘q — COUNT(*) bajarilmaydi)
ProductResource orqali)COUNT(*) bilanpublic function index(Request $request) { $request->validate([ 'per_page' => ['integer', 'between:1,100'], 'sort' => ['in:name,-name,price,-price,created_at,-created_at'], 'category_id' => ['integer', 'exists:categories,id'], ]); $sort = $request->string('sort', 'name')->toString(); $direction = str_starts_with($sort, '-') ? 'desc' : 'asc'; return ProductResource::collection( Product::with('category') ->when($request->integer('category_id'), fn ($q, $id) => $q->where('category_id', $id)) ->orderBy(ltrim($sort, '-'), $direction) ->paginate($request->integer('per_page', 20)) ); }
GET /api/v1/products?sort=-price&category_id=3 → 200, qimmatidan arzoniga
GET /api/v1/products?sort=password → 422 {"errors": {"sort": [...]}}
GET /api/v1/products?per_page=1000 → 422in:name,-name,... — saralash ustuni oq ro‘yxatdan — SQL injection va ichki ustunlar yopiq$request->string() — Laravel Stringable qaytaradi; toString() — oddiy satrwhen(..., fn ...) — filtr faqat parametr berilganda qo‘llanadibetween:1,100 — katta per_page jim kesilmaydi, 422 bilan rad etiladiprice maydonini satrdan songa o‘zgartirish nima uchun yangi versiya talab qiladi?Mavjud mijozlar satr kutadi; tur o‘zgarishi ularni buzadi — bu buzuvchi o‘zgarish.
Offset sahifa raqami va jami sonni beradi, lekin katta jadvalda sekin; cursor oxirgi kalitdan davom etadi — tez, lekin jami son yo‘q.
sort parametrini oq ro‘yxat bilan tekshirish kerak?Aks holda foydalanuvchi ichki ustun yoki SQL ifoda bo‘yicha saralashga urinishi mumkin; ruxsat etilgan ro‘yxat buni yopadi.
application/problem+json · type, title, status, detail, instance · withExceptions · maxfiylik
Mijoz dasturchisi uchun eng qimmat narsa — bashorat qilinadigan xatolar. Agar bir endpoint {"error": "..."}, ikkinchisi {"msg": "..."}, uchinchisi HTML xato sahifasini qaytarsa, har bir holat uchun alohida kod yoziladi. RFC 7807 “Problem Details for HTTP APIs” (2016; 2023 yilda RFC 9457 bilan yangilangan, maydonlar o‘sha) yagona JSON formatini taklif qiladi va application/problem+json media turini belgilaydi.
Standart maydonlar: type — xato turini aniqlaydigan URI (hujjat sahifasiga ishora qilishi mumkin, masalan https://omborpro.test/problems/insufficient-stock; tur aniqlanmagan bo‘lsa — about:blank), title — tur uchun qisqa, o‘zgarmas sarlavha, status — HTTP status kodi, detail — aynan shu holat uchun inson o‘qiydigan izoh, instance — muammo yuz bergan so‘rov URI si. Qo‘shimcha maydonlar (extension) ham ruxsat etiladi: validatsiya uchun errors, qoldiq xatosi uchun available va requested, kuzatish uchun trace_id. Mijoz mantiqni type va status ga quradi, detail esa faqat ko‘rsatish uchun.
Laravel 12 da xatolarni render qilish bootstrap/app.php dagi withExceptions() ichida sozlanadi. $exceptions->render(function (DomainException $e, Request $r) {...}) — berilgan turdagi (va undan meros olgan) istisnolar uchun javob yasaydi; null qaytarilsa, Laravel standart render ga o‘tadi. Shu tufayli servis qatlamidagi InsufficientStockException va InvalidStatusTransitionException (ikkalasi DomainException dan meros) controllerda try/catch siz 409 ga aylanadi. $exceptions->shouldRenderJsonWhen(...) esa api/* yo‘llari uchun Accept sarlavhasi bo‘lmasa ham JSON qaytarishni ta’minlaydi.
Validatsiya xatolari uchun Laravel o‘z formatini beradi: 422 va {"message": "...", "errors": {"sku": ["..."]}}. Ko‘p jamoalar uni o‘zgartirmaydi — mijoz kutubxonalari (masalan, frontend formalar) aynan shu formatni tushunadi; problem+json da errors kengaytma maydon sifatida saqlanadi. Asosiysi — butun API bo‘ylab bitta qarorga amal qilish va uni OpenAPI da hujjatlash.
Xatolarda maxfiylik: productionda APP_DEBUG=false bo‘lishi shart, aks holda 500 javobida stack trace, SQL so‘rov va fayl yo‘llari chiqadi — bu OWASP ro‘yxatidagi ma’lumot sizib chiqishi. 500 uchun mijozga umumiy detail (“Kutilmagan xato”) va trace_id beriladi, tafsilotlar esa faqat logga yoziladi. 404 da “bunday email bilan foydalanuvchi yo‘q” kabi ortiqcha ma’lumot bermaslik ham muhim — u hisoblarni sanab chiqishga yordam beradi.
Har bir xato bir xil shaklda: Content-Type: application/problem+json va beshta standart maydon.
.../problems/insufficient-stock, “Qoldiq yetarli emas”.409 — proxy kodni o‘zgartirsa ham asl qiymat saqlanadi./api/v1/orders/42/confirm.errors (validatsiya), available, trace_id.type ga qarab qaror qiladi; detail matni o‘zgarishi mumkin, unga tayanmang.<?php final class InsufficientStockException extends DomainException {} function problem(Throwable $e, string $uri): array { [$status, $title] = match (true) { $e instanceof DomainException => [409, 'Biznes-qoida buzildi'], $e instanceof InvalidArgumentException => [422, 'Validatsiya'], default => [500, 'Ichki xato'], }; $detail = $status === 500 ? 'Kutilmagan xato' : $e->getMessage(); return ['type' => 'about:blank', 'title' => $title, 'status' => $status, 'detail' => $detail, 'instance' => $uri]; } $e = new InsufficientStockException('UN-001: mavjud 3, so‘ralgan 5'); $flags = JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES; echo json_encode(problem($e, '/api/v1/orders/42/confirm'), $flags);
{
"type": "about:blank",
"title": "Biznes-qoida buzildi",
"status": 409,
"detail": "UN-001: mavjud 3, so‘ralgan 5",
"instance": "/api/v1/orders/42/confirm"
}match (true) — istisno turiga qarab status va sarlavha tanlanadi$e instanceof DomainException — InsufficientStockException ham shu shartga tushadi (meros)$status === 500 — kutilmagan xatoda ichki xabar mijozga chiqmaydi\u2018 ga aylanmaydireturn Application::configure(basePath: dirname(__DIR__)) // ->withRouting(...)->withMiddleware(...) ->withExceptions(function (Exceptions $exceptions) { $exceptions->shouldRenderJsonWhen( fn (Request $r, Throwable $e) => $r->is('api/*')); $exceptions->render(function (DomainException $e, Request $r) { if (! $r->is('api/*')) { return null; // web: odatiy xato sahifasi } return response()->json([ 'type' => 'https://omborpro.test/problems/conflict', 'title' => 'Biznes-qoida buzildi', 'status' => 409, 'detail' => $e->getMessage(), 'instance' => $r->getRequestUri(), ], 409, ['Content-Type' => 'application/problem+json']); }); })->create();
POST /api/v1/orders/42/confirm
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{"type": "https://omborpro.test/problems/conflict", "status": 409,
"detail": "UN-001: mavjud 3, so‘ralgan 5", ...}api/* uchun har doim JSON — HTML xato sahifasi yo‘qrender(DomainException ...) — servis qatlamidagi barcha biznes-xatolar bitta joydaapplication/problem+json — RFC 7807 media turi sarlavhada200 OK + {"success": false, "msg": "xato"}error, message, msgAPP_DEBUG=true)type, title, status, detail, instancetrace_id, tafsilot logdaapi/* uchun har doim JSON (shouldRenderJsonWhen)type, title, status, detail, instance (+ kengaytma maydonlar).
InsufficientStockException qanday qilib controllerda try/catch siz 409 javobga aylanadi?bootstrap/app.php da $exceptions->render() DomainException (va merosxo‘rlari) uchun problem+json javobini yasaydi.
APP_DEBUG=false bo‘lishi shart?Aks holda xato javobida stack trace, SQL va fayl yo‘llari chiqadi — bu ma’lumot sizib chiqishi.
Bearer token · JWT tuzilmasi va imzo · exp va refresh · jwt-auth · Sanctum bilan solishtirish
API stateless bo‘lgani uchun sessiya cookie o‘rniga token ishlatiladi: mijoz login qilib token oladi va keyingi har bir so‘rovda Authorization: Bearer <token> sarlavhasini yuboradi. Tokenning ikki turi bor. Shaffof bo‘lmagan (opaque) token — tasodifiy satr, server uni bazadagi yozuv bilan solishtiradi (Laravel Sanctum shunday: token personal_access_tokens jadvalida SHA-256 xesh ko‘rinishida saqlanadi). O‘zini tavsiflovchi (self-contained) token — JWT: foydalanuvchi ID, rol va muddat tokenning o‘zida, imzo bilan himoyalangan; server bazaga murojaat qilmasdan imzoni tekshiradi.
JWT (JSON Web Token, RFC 7519) uch qismdan iborat va nuqta bilan ajratiladi: header.payload.signature. Har bir qism — base64url kodlangan (+ → -, / → _, = olib tashlanadi). Header: {"alg":"HS256","typ":"JWT"}. Payload — da’volar (claims): sub (foydalanuvchi ID), iat (berilgan vaqt), exp (tugash vaqti, Unix sekund), iss, jti (token ID) va o‘zimizniki — role. HS256 da imzo = HMAC-SHA256(header.payload, sir_kalit); RS256 da maxfiy kalit bilan imzolanadi, ochiq kalit bilan tekshiriladi — tokenni bir nechta servis tekshirishi kerak bo‘lganda qulay.
Eng muhim tushuncha: payload shifrlanmagan, faqat kodlangan. Uni har kim jwt.io da o‘qiy oladi. Demak, unga parol, STIR, karta raqami yoki boshqa maxfiy ma’lumot yozilmaydi. Imzo faqat o‘zgartirilmaganini kafolatlaydi: role ni admin ga almashtirgan hujumchi to‘g‘ri imzo yasay olmaydi. Tekshiruvda imzo hash_equals() bilan solishtiriladi (vaqt bo‘yicha hujumdan himoya), alg server tomonida qat’iy belgilanadi (none algoritmini qabul qilmaslik), exp albatta tekshiriladi, sir kalit uzun va tasodifiy bo‘ladi.
JWT ning zaif tomoni — bekor qilish: token muddati tugaguncha amal qiladi. Shuning uchun access token qisqa (15–60 daqiqa), yangilash (refresh) mexanizmi bilan ishlatiladi; chiqishda token qora ro‘yxatga (blacklist) qo‘shiladi. php-open-source-saver/jwt-auth paketida: config/jwt.php da ttl (daqiqa, standart 60) va refresh_ttl, auth('api')->attempt() login qilib token qaytaradi, auth('api')->refresh() yangi token beradi, auth('api')->logout() joriy tokenni qora ro‘yxatga yozadi (blacklist_enabled). User modeli JWTSubject interfeysini amalga oshiradi: getJWTIdentifier() va getJWTCustomClaims().
Sanctum — Laravel ning rasmiy yengil yechimi va install:api uni standart o‘rnatadi. U ikki ish qiladi: SPA uchun cookie-sessiya autentifikatsiyasi va mobil/integratsiya uchun shaxsiy tokenlar ($user->createToken('mobil', ['orders:read'])->plainTextToken, auth:sanctum middleware, $user->tokenCan('orders:read')). Tokenni bazadan o‘chirib, darhol bekor qilish mumkin. OmborPro kursida mobil va tashqi mijozlar uchun JWT ni o‘rganamiz (bazasiz tekshiruv, da’volar), lekin Sanctum ko‘p loyihalar uchun soddaroq va xavfsizroq tanlov ekanini bilish kerak.
JWT — imzolangan, lekin shifrlanmagan token. Uch qism base64url kodlangan va nuqta bilan birlashtirilgan.
{"alg":"HS256","typ":"JWT"} → eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9sub, iat, exp, jti + role. Har kim o‘qiy oladi — maxfiy ma’lumot yozilmaydi.HMAC-SHA256(header.payload, JWT_SECRET). O‘zgartirilgan payload imzodan o‘tmaydi.alg kutilganmi → imzo hash_equals → exp > hozirgi vaqt.<?php function b64url(string $s): string { return rtrim(strtr(base64_encode($s), '+/', '-_'), '='); } $key = 'faqat-test-uchun-sir-kalit-2026'; $sign = fn ($d) => b64url(hash_hmac('sha256', $d, $key, true)); $h = b64url(json_encode(['alg' => 'HS256', 'typ' => 'JWT'])); $p = b64url(json_encode(['sub' => 7, 'role' => 'menejer'])); $jwt = "$h.$p." . $sign("$h.$p"); echo $h, PHP_EOL; [$h2, $p2, $s2] = explode('.', $jwt); echo base64_decode(strtr($p2, '-_', '+/')), PHP_EOL; $admin = b64url(json_encode(['sub' => 7, 'role' => 'admin'])); foreach ([$p2, $admin] as $payload) { $ok = hash_equals($sign("$h2.$payload"), $s2); echo $ok ? "imzo to‘g‘ri\n" : "soxta token\n"; }
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
{"sub":7,"role":"menejer"}
imzo to‘g‘ri
soxta tokenb64url() — base64 → URL uchun xavfsiz: +/ → -_, = yo‘qhash_hmac(..., true) — xom (binary) HMAC-SHA256, keyin base64urlbase64_decode($p2) — payload sirsiz o‘qiladi — u shifrlanmaganhash_equals() — doimiy vaqtli solishtirish; role: admin ga almashtirilgan payload rad etiladipublic function login(Request $request) { $credentials = $request->validate( ['email' => 'required|email', 'password' => 'required']); $token = auth('api')->attempt( $credentials + ['is_active' => true]); if (! $token) { return response()->json( ['message' => 'Email yoki parol noto‘g‘ri'], 401); } return response()->json([ 'access_token' => $token, 'token_type' => 'bearer', 'expires_in' => auth('api')->factory()->getTTL() * 60, ]); }
POST /api/v1/auth/login → 200
{"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3Mi...",
"token_type": "bearer", "expires_in": 3600}auth('api') — config/auth.php dagi 'api' => ['driver' => 'jwt', ...] guardattempt($credentials + ...) — parolni xesh bilan tekshiradi; is_active = true sharti qo‘shiladigetTTL() * 60 — jwt.ttl daqiqada (standart 60) → sekundrefresh() / logout() — yangi token berish va joriysini qora ro‘yxatga yozishcreateToken('mobil', ['orders:read'])ttl + refresh + blacklistJWT_SECRET faqat .env dathrottle.Payload shifrlanmagan, faqat base64url kodlangan — uni har kim o‘qiy oladi.
== emas, hash_equals() ishlatiladi?hash_equals doimiy vaqtda solishtiradi; == birinchi farqda to‘xtaydi va vaqt bo‘yicha hujumga yo‘l ochadi.
Sanctum tokeni bazada saqlanadi va har so‘rovda tekshiriladi — yozuvni o‘chirish yetarli; JWT esa bazasiz tekshiriladi.
OpenAPI 3 · knuckleswtf/scribe · docblock teglari · /docs · Postman kolleksiyasi
API — shartnoma, shartnoma esa yozma bo‘lishi kerak. OpenAPI (avvalgi nomi Swagger) — REST API ni mashina o‘qiy oladigan YAML/JSON ko‘rinishida tavsiflash standarti: paths (endpointlar, parametrlar, javoblar), components.schemas (ma’lumot sxemalari), components.securitySchemes (masalan, Bearer JWT). Bitta OpenAPI fayldan interaktiv hujjat sahifasi, mijoz kutubxonalari (generator orqali) va test so‘rovlar yasaladi. Hujjatni qo‘lda yozish va yangilab turish qiyin — u tezda koddan orqada qoladi.
Scribe (knuckleswtf/scribe) hujjatni Laravel kodining o‘zidan yasaydi: marshrutlarni o‘qiydi, Form Request dagi rules() dan so‘rov tanasi parametrlarini, docblock teglaridan izohlarni, API Resource va factory dan javob namunalarini oladi. O‘rnatish: composer require --dev knuckleswtf/scribe, php artisan vendor:publish --tag=scribe-config, keyin php artisan scribe:generate. config/scribe.php da routes (qaysi yo‘llar — api/*), auth (Bearer token qayerda yuboriladi), postman va openapi bo‘limlari yoqiladi. type = laravel bo‘lsa, hujjat ilova ichida /docs manzilida, Postman kolleksiyasi /docs.postman, OpenAPI spetsifikatsiyasi /docs.openapi da beriladi.
Docblock teglari: @group Mahsulotlar — bo‘lim, @authenticated — token kerak, @urlParam, @queryParam, @bodyParam — parametrlar (Example: bilan namunaviy qiymat), @response 201 {...} — qo‘lda javob namunasi, @apiResourceCollection va @apiResourceModel — javobni Resource va factory dan avtomatik yasash. Docblock birinchi qatori endpoint nomi, keyingi paragraf — tavsif bo‘ladi. Biznes-qoidalarni ham yozing: “buyurtma draft holatida yaratiladi, rezerv confirm da qilinadi”.
Postman kolleksiyasi — jamoa va mijozlar uchun tayyor so‘rovlar to‘plami. Scribe yasagan collection.json Postman ga import qilinadi; muhit (environment) o‘zgaruvchilari baseUrl va token bilan bir xil kolleksiya lokal, test va production serverda ishlaydi. Login so‘roviga test-skript qo‘shib, olingan tokenni avtomatik token o‘zgaruvchisiga yozish mumkin. Kolleksiyani newman CLI bilan buyruq qatorida ham yugurtirsa bo‘ladi — bu API ning qo‘lda emas, avtomatik tekshiriladigan shartnomasiga aylanishi.
openapi: 3.0.3 info: {title: OmborPro API, version: 1.0.0} servers: - url: https://omborpro.test/api/v1 paths: /products/{id}: get: summary: Mahsulotni olish security: [{bearerAuth: []}] parameters: - {name: id, in: path, required: true, schema: {type: integer}} responses: '200': {description: Mahsulot (ProductResource)} '401': {description: Token yo‘q yoki muddati o‘tgan} '404': {description: Topilmadi (problem+json)} components: securitySchemes: bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
Scribe → /docs (HTML hujjat), /docs.openapi (shu YAML), /docs.postman (kolleksiya)
components da tavsiflanadi/** * Mahsulotlar ro‘yxati * * Nomi bo‘yicha saralangan, sahifalangan katalog. * * @group Mahsulotlar * @authenticated * @queryParam category_id integer Kategoriya filtri. Example: 3 * @queryParam sort string Saralash maydoni. Example: -price * @queryParam per_page integer 1–100 oralig‘ida. Example: 20 * @apiResourceCollection App\Http\Resources\ProductResource * @apiResourceModel App\Models\Product with=category paginate=20 */ public function index(Request $request) { // ... }
$ php artisan scribe:generate Processing route: [GET,HEAD] api/v1/products Processed route: [GET,HEAD] api/v1/products ... Checking for any pending upgrades to your config file...
Authorization sarlavhasi@queryParam ... Example: — parametr turi, izohi va namunaviy qiymati@apiResourceModel ... paginate=20 — javob namunasi factory + Resource dan, sahifalash bilancomposer require --dev knuckleswtf/scribe, vendor:publish --tag=scribe-configconfig/scribe.php: routes → api/*, auth.enabled → Bearer, postman va openapi yoqilgan@group, @authenticated, @queryParam, @response teglariphp artisan scribe:generate → /docs, /docs.openapi, /docs.postmanbaseUrl va token muhit o‘zgaruvchilarinewman run bilan kolleksiyani buyruq qatorida yugurtirishscribe:generate qayta ishga tushiriladi — hujjat koddan orqada qolmasin.info/servers, paths (endpointlar va javoblar), components (sxemalar va securitySchemes).
Form Request dagi rules() dan, qo‘shimcha ravishda @bodyParam docblock teglaridan.
baseUrl, token) nima uchun kerak?Bir xil kolleksiyani turli serverlarda (lokal, test) ishlatish va login tokenini barcha so‘rovlarga avtomatik qo‘yish uchun.
GET /api/v1/products, POST /api/v1/orders/42/confirm; URI da get, create yo‘q.Location, 204, 401/403, 404, 409 (biznes-qoida), 422 (validatsiya), 429.whenLoaded./api/v1, buzuvchi o‘zgarish faqat yangi versiyada; per_page 1–100, cursor — katta jurnallar uchun.type, title, status, detail, instance; withExceptions() da markazlashgan.ttl; Scribe → OpenAPI + Postman kolleksiyasi.Takroriy yuborilganda server holati bir xil bo‘ladigan metod: GET, PUT, DELETE.
201 Created va Location: /api/v1/orders/42.
409 Conflict — so‘rov to‘g‘ri, lekin biznes-holat bilan to‘qnashdi.
whenLoaded('category') nima qiladi?Relation yuklangan bo‘lsagina JSON ga qo‘shadi — N+1 va keraksiz so‘rovdan saqlaydi.
Katta jadvalda COUNT va OFFSET sekin, yangi yozuvlar qo‘shilsa sahifalar siljiydi.
application/problem+json.
header, payload, signature — base64url, nuqta bilan ajratilgan.
php artisan scribe:generate — har bir API o‘zgarishidan keyin.