7

7-ma’ruza matni · Korxona ilovalarini dasturlash

REST API loyihalash

Resurslar va HTTP · API Resource · versiya va sahifalash · xatolar formati · JWT · OpenAPI

Muammoli savol

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.

Javob

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.

O‘quv maqsadlari

  • Tushuntirish — REST tamoyillari, resurs va uning ko‘rinishi (representation) tushunchalarini
  • Farqlash — HTTP metodlarining xavfsiz va idempotent xossalarini hamda 2xx/4xx/5xx status kodlarini
  • Loyihalash — OmborPro uchun /api/v1 resurslar daraxti, sahifalash va filtrlash parametrlarini
  • Qo‘llash — Laravel 12 da Route::apiResource, API Resource va Form Request ni
  • Yozish — RFC 7807 (Problem Details) formatidagi yagona xato javoblarini
  • Tavsiflash — JWT tuzilmasi, imzo va muddat (exp), Sanctum tokenlaridan farqini
  • Yaratish — Scribe yordamida OpenAPI hujjati va Postman kolleksiyasini
  • Baholash — API dizaynidagi xatolarni: noto‘g‘ri status kod, chegarasiz per_page, ma’lumot sizib chiqishi
Ma’ruza rejasi
  1. REST resurslari va HTTP semantikasi
  2. Laravel’da API: marshrutlar, controller va API Resource
  3. Versiyalash, sahifalash va filtrlash
  4. Xatolar formati: Problem Details (RFC 7807)
  5. Autentifikatsiya: token, JWT va Sanctum
  6. OpenAPI hujjatlari: Scribe va Postman

1. REST resurslari va HTTP semantikasi

Resurs 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

Resurs, URI va ko‘rinish

REST API — resurslar ustida standart HTTP metodlari bilan ishlash shartnomasi. URI — ot, metod — fe’l.

Resurs
Biznes obyekti yoki to‘plam: products, orders/42, orders/42/items.
Ko‘rinish
Resursning JSON tasviri — jadval ustunlari emas, mijoz uchun barqaror shartnoma.
Stateless
Har bir so‘rov o‘zi yetarli: token har safar Authorization sarlavhasida keladi.
Amal-endpoint
CRUD ga sig‘maydigan o‘tish: 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.
HTTP METODLARI

Metod nimani anglatadi?

MetodOmborPro misoliXavfsizIdempotent
GETGET /products?page=2 — ro‘yxathaha
POSTPOST /orders — yangi buyurtmayo‘qyo‘q
PUTPUT /products/15 — to‘liq almashtirishyo‘qha
PATCHPATCH /products/15 — narxni o‘zgartirishyo‘qkafolatlanmaydi
DELETEDELETE /products/15 — soft deleteyo‘qha
POST (amal)POST /orders/42/confirm — holat o‘tishiyo‘qyo‘q
POST ni xavfsiz takrorlash uchun Idempotency-Key sarlavhasi: server shu kalit bilan birinchi javobni saqlab, takroriy so‘rovga qaytaradi.
STATUS KODLAR

Qaysi holatda qaysi kod?

KodMa’nosiOmborPro misoli
200 OKmuvaffaqiyat, tanada natijamahsulotlar ro‘yxati
201 Createdyangi resurs + Locationbuyurtma yaratildi
204 No Contentmuvaffaqiyat, tana yo‘qmahsulot o‘chirildi
401 Unauthorizedtoken yo‘q yoki muddati o‘tganexp o‘tib ketgan JWT
403 Forbiddentoken bor, ruxsat yo‘qomborchi hisob-fakturani so‘radi
404 Not Foundresurs topilmadi/products/9999
409 Conflictbiznes-qoida to‘qnashuvirezerv uchun qoldiq yetarli emas
422 Unprocessablevalidatsiya xatosisku band, price manfiy
Yana: 400 — buzuq JSON, 429 — limit oshdi (Retry-After), 500 — kutilmagan server xatosi.

Status kodni tanlang

Har bir vaziyat uchun eng to‘g‘ri HTTP javob kodini tanlang.

POST /api/v1/orders muvaffaqiyatli, yangi buyurtma yaratildi.
  1. 200
  2. 201
  3. 204
  4. 202

✓ 201 — Yangi resurs yaratilganda 201 Created va Location sarlavhasi qaytariladi.

Rezerv qilish uchun UN-001 dan 5 dona kerak, mavjud qoldiq 3.
  1. 400
  2. 404
  3. 500
  4. 409

✓ 409 — So‘rov to‘g‘ri tuzilgan, lekin biznes-holat bilan to‘qnashadi — 409 Conflict.

Omborchi roli bilan GET /api/v1/invoices so‘raldi; token yaroqli.
  1. 403
  2. 401
  3. 404
  4. 422

✓ 403 — Foydalanuvchi aniqlangan, lekin ruxsati yo‘q — 403 Forbidden.

price maydoni -500 bo‘lib keldi.
  1. 409
  2. 400
  3. 422
  4. 500

✓ 422 — Maydon qiymati qoidaga zid — validatsiya xatosi, Laravel 422 qaytaradi.

O‘zingizni tekshiring
Nima uchun /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 va 403 status kodlari qachon qaytariladi?

401 — foydalanuvchi aniqlanmadi (token yo‘q/yaroqsiz); 403 — aniqlandi, lekin ruxsati yo‘q.

2. Laravel’da API: marshrutlar, controller va API Resource

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.

routes/api.php

Versiyalangan marshrutlar guruhi

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']);
    });
});
▶ Natija
$ 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}/confirm
  • prefix('v1') — /api + /v1 — URL da versiya; nomlar v1.products.index
  • throttle:5,1 — login uchun daqiqasiga 5 urinish — parol tanlashdan himoya
  • auth:api — api guard (JWT) — tokensiz so‘rov 401 oladi
  • apiResource — index, store, show, update, destroy — create/edit yo‘q
  • orders/{order}/confirm — CRUD dan tashqari biznes-amal, OrderService ni chaqiradi
CONTROLLER

Ingichka API controller

class 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));
    }
}
▶ Natija
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/16
  • min(max(..., 1), 100) — per_page chegarasi — 1 000 000 yozuvli javobdan himoya
  • with('category') — eager loading — Resource ichida N+1 bo‘lmaydi
  • withQueryString() — filtrlar links.next ichida saqlanadi
  • $request->validated() — faqat qoidalardan o‘tgan maydonlar
  • ->response()->header() — 201 avtomatik, Location ni biz qo‘shamiz
API RESOURCE

ProductResource — barqaror JSON shartnomasi

class 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)],
        ];
    }
}
▶ Natija
{"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‘q
  • whenLoaded('category') — relation yuklanmagan bo‘lsa, kalit umuman chiqmaydi
  • toIso8601String() — sana vaqt zonasi bilan (Asia/Tashkent, +05:00)
  • {"data": ...} — Resource javobni standart holda data ichiga o‘raydi
HTTP SO‘ROV

Mijoz nima yuboradi va nima oladi

POST /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}
▶ Natija
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 saqlanadi
  • 201 + Location — mijoz yangi resurs manzilini darhol biladi
O‘zingizni tekshiring
Route::apiResource qaysi metodlarni yaratadi va Route::resource dan farqi nimada?

index, store, show, update, destroy; HTML formalar uchun create va edit yo‘q.

Nima uchun modelni API dan to‘g‘ridan-to‘g‘ri qaytarmasdan API Resource ishlatamiz?

Maydonlarni nazorat qilish (maxfiy ustunlar chiqmasligi), barqaror shartnoma, format (sana, pul), relationlarni shartli qo‘shish.

Yangi resurs yaratilganda Laravel 201 statusni qanday aniqlaydi?

Resource dagi model wasRecentlyCreated bo‘lsa, ResourceResponse statusni avtomatik 201 qiladi.

3. Versiyalash, sahifalash va filtrlash

/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.

VERSIYALASH

Qaysi o‘zgarish yangi versiya talab qiladi?

✗ Buzuvchi — faqat /api/v2 da
  • maydonni o‘chirish yoki qayta nomlash: name → title
  • turini o‘zgartirish: "price": "385000.00" → 385000
  • yangi majburiy parametr: warehouse_id endi shart
  • status kod ma’nosini o‘zgartirish: 409 o‘rniga 422
  • sahifalash formatini o‘zgartirish
✓ Buzmaydi — /api/v1 ga qo‘shiladi
  • yangi ixtiyoriy maydon: "barcode": null
  • yangi endpoint: GET /api/v1/warehouses
  • yangi ixtiyoriy filtr: ?is_active=1
  • xato detail matnini aniqlashtirish
  • unumdorlikni oshirish, indeks qo‘shish
Eskirgan versiya: hujjatda tugash sanasi va javobda Sunset: Sat, 01 May 2027 00:00:00 GMT sarlavhasi.
SAHIFALASH META

meta qanday hisoblanadi (sof PHP)

<?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;
▶ Natija
{"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 sahifa
  • min($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
JSON JAVOB

Sahifalangan Resource collection

{
  "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
  }
}
▶ Natija
cursorPaginate() da meta: path, per_page, next_cursor, prev_cursor
(total va last_page yo‘q — COUNT(*) bajarilmaydi)
  • data — joriy sahifa yozuvlari (ProductResource orqali)
  • links.next — mijoz keyingi sahifani URL ni o‘zi tuzmasdan oladi
  • meta.total — jami yozuvlar — offset sahifalashda COUNT(*) bilan
  • meta.links — Laravel bu yerga sahifa tugmalari ro‘yxatini ham qo‘shadi (qisqartirildi)
FILTR VA SARALASH

Ruxsat etilgan parametrlar ro‘yxati

public 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))
    );
}
▶ Natija
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              → 422
  • in:name,-name,... — saralash ustuni oq ro‘yxatdan — SQL injection va ichki ustunlar yopiq
  • $request->string() — Laravel Stringable qaytaradi; toString() — oddiy satr
  • when(..., fn ...) — filtr faqat parametr berilganda qo‘llanadi
  • between:1,100 — katta per_page jim kesilmaydi, 422 bilan rad etiladi
O‘zingizni tekshiring
price 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 va cursor sahifalashning asosiy farqi nimada?

Offset sahifa raqami va jami sonni beradi, lekin katta jadvalda sekin; cursor oxirgi kalitdan davom etadi — tez, lekin jami son yo‘q.

Nima uchun 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.

4. Xatolar formati: Problem Details (RFC 7807)

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.

RFC 7807 / 9457

Problem Details maydonlari

Har bir xato bir xil shaklda: Content-Type: application/problem+json va beshta standart maydon.

type va title
Xato turi URI si va uning o‘zgarmas nomi: .../problems/insufficient-stock, “Qoldiq yetarli emas”.
status
HTTP status kodi takrori: 409 — proxy kodni o‘zgartirsa ham asl qiymat saqlanadi.
detail va instance
Aynan shu holat izohi va so‘rov yo‘li: “UN-001: mavjud 3, so‘ralgan 5”, /api/v1/orders/42/confirm.
Kengaytmalar
Qo‘shimcha maydonlar: errors (validatsiya), available, trace_id.
Mijoz kodi type ga qarab qaror qiladi; detail matni o‘zgarishi mumkin, unga tayanmang.
SOF PHP

Istisnodan problem+json gacha

<?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);
▶ Natija
{
    "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
  • JSON_UNESCAPED_UNICODE — o‘zbekcha harflar \u2018 ga aylanmaydi
bootstrap/app.php

Laravel 12 da xatolarni render qilish

return 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();
▶ Natija
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", ...}
  • shouldRenderJsonWhen — api/* uchun har doim JSON — HTML xato sahifasi yo‘q
  • render(DomainException ...) — servis qatlamidagi barcha biznes-xatolar bitta joyda
  • return null — web marshrutlarida standart render saqlanadi
  • application/problem+json — RFC 7807 media turi sarlavhada
XATO JAVOBLARI

Yomon va yaxshi xato javobi

✗ Noto‘g‘ri
  • 200 OK + {"success": false, "msg": "xato"}
  • har endpointda boshqa format: error, message, msg
  • 500 javobida stack trace va SQL (APP_DEBUG=true)
  • API so‘roviga HTML xato sahifasi yoki 302 redirect
✓ To‘g‘ri
  • mos status: 404, 409, 422, 429
  • yagona format: type, title, status, detail, instance
  • 500 da umumiy matn + trace_id, tafsilot logda
  • api/* uchun har doim JSON (shouldRenderJsonWhen)
O‘zingizni tekshiring
RFC 7807 bo‘yicha xato javobining standart maydonlarini sanang.

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.

Nima uchun productionda APP_DEBUG=false bo‘lishi shart?

Aks holda xato javobida stack trace, SQL va fayl yo‘llari chiqadi — bu ma’lumot sizib chiqishi.

5. Autentifikatsiya: token, JWT va Sanctum

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

header.payload.signature

JWT — imzolangan, lekin shifrlanmagan token. Uch qism base64url kodlangan va nuqta bilan birlashtirilgan.

Header
{"alg":"HS256","typ":"JWT"} → eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Payload
Da’volar: sub, iat, exp, jti + role. Har kim o‘qiy oladi — maxfiy ma’lumot yozilmaydi.
Signature
HS256: HMAC-SHA256(header.payload, JWT_SECRET). O‘zgartirilgan payload imzodan o‘tmaydi.
Tekshiruv tartibi: 3 qism bormi → alg kutilganmi → imzo hash_equals → exp > hozirgi vaqt.
SOF PHP

HS256 imzosini yasash va tekshirish

<?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";
}
▶ Natija
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
{"sub":7,"role":"menejer"}
imzo to‘g‘ri
soxta token
  • b64url() — base64 → URL uchun xavfsiz: +/ → -_, = yo‘q
  • hash_hmac(..., true) — xom (binary) HMAC-SHA256, keyin base64url
  • base64_decode($p2) — payload sirsiz o‘qiladi — u shifrlanmagan
  • hash_equals() — doimiy vaqtli solishtirish; role: admin ga almashtirilgan payload rad etiladi
jwt-auth

Login: token berish

public 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,
    ]);
}
▶ Natija
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', ...] guard
  • attempt($credentials + ...) — parolni xesh bilan tekshiradi; is_active = true sharti qo‘shiladi
  • getTTL() * 60 — jwt.ttl daqiqada (standart 60) → sekund
  • 401 — qaysi maydon xato ekanini aytmaymiz — hisoblarni sanashdan himoya
  • refresh() / logout() — yangi token berish va joriysini qora ro‘yxatga yozish
TANLOV

Sanctum tokeni va JWT

Sanctum (opaque token)
  • tasodifiy satr, bazada SHA-256 xesh
  • har so‘rovda bazaga murojaat
  • darhol bekor qilish: yozuvni o‘chirish
  • huquqlar: createToken('mobil', ['orders:read'])
  • SPA uchun cookie-sessiya rejimi ham bor
JWT (jwt-auth)
  • imzolangan JSON, da’volar ichida
  • bazasiz tekshiruv — servislar orasida qulay
  • bekor qilish qiyin: qisqa ttl + refresh + blacklist
  • payload o‘qiladi — maxfiy ma’lumot yo‘q
  • kalitni himoyalash shart: JWT_SECRET faqat .env da
Ikkala holatda ham: faqat HTTPS, tokenni URL ga yozmaslik (loglarga tushadi), login uchun throttle.
O‘zingizni tekshiring
JWT payloadiga nima uchun parol yoki STIR yozib bo‘lmaydi?

Payload shifrlanmagan, faqat base64url kodlangan — uni har kim o‘qiy oladi.

JWT imzosini tekshirishda nima uchun == emas, hash_equals() ishlatiladi?

hash_equals doimiy vaqtda solishtiradi; == birinchi farqda to‘xtaydi va vaqt bo‘yicha hujumga yo‘l ochadi.

Sanctum tokenini JWT dan osonroq bekor qilish mumkinligi sababi nimada?

Sanctum tokeni bazada saqlanadi va har so‘rovda tekshiriladi — yozuvni o‘chirish yetarli; JWT esa bazasiz tekshiriladi.

6. OpenAPI hujjatlari: Scribe va Postman

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

Spetsifikatsiya bo‘lagi

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}
▶ Natija
Scribe → /docs (HTML hujjat), /docs.openapi (shu YAML), /docs.postman (kolleksiya)
  • servers — bazaviy URL — versiya shu yerda
  • paths — har bir endpoint: parametrlar va mumkin bo‘lgan javoblar
  • security — bu endpoint Bearer JWT talab qiladi
  • securitySchemes — token turi bir marta, components da tavsiflanadi
SCRIBE

Controller dagi docblock teglari

/**
 * 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)
{
    // ...
}
▶ Natija
$ 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...
  • @group — hujjatdagi bo‘lim: Mahsulotlar, Buyurtmalar, Autentifikatsiya
  • @authenticated — “token kerak” belgisi va Postman da Authorization sarlavhasi
  • @queryParam ... Example: — parametr turi, izohi va namunaviy qiymati
  • @apiResourceModel ... paginate=20 — javob namunasi factory + Resource dan, sahifalash bilan
ISH OQIMI

Koddan Postman kolleksiyasigacha

  1. O‘rnatish — composer require --dev knuckleswtf/scribe, vendor:publish --tag=scribe-config
  2. Sozlash — config/scribe.php: routes → api/*, auth.enabled → Bearer, postman va openapi yoqilgan
  3. Izohlash — controllerlarga @group, @authenticated, @queryParam, @response teglari
  4. Yaratish — php artisan scribe:generate → /docs, /docs.openapi, /docs.postman
  5. Postman — kolleksiyani import, baseUrl va token muhit o‘zgaruvchilari
  6. Avtomatlash — newman run bilan kolleksiyani buyruq qatorida yugurtirish
Har bir API o‘zgarishidan keyin scribe:generate qayta ishga tushiriladi — hujjat koddan orqada qolmasin.
O‘zingizni tekshiring
OpenAPI hujjatining uchta asosiy bo‘limini ayting.

info/servers, paths (endpointlar va javoblar), components (sxemalar va securitySchemes).

Scribe so‘rov tanasi parametrlarini qayerdan oladi?

Form Request dagi rules() dan, qo‘shimcha ravishda @bodyParam docblock teglaridan.

Postman muhit o‘zgaruvchilari (baseUrl, token) nima uchun kerak?

Bir xil kolleksiyani turli serverlarda (lokal, test) ishlatish va login tokenini barcha so‘rovlarga avtomatik qo‘yish uchun.

Asosiy xulosalar

Takrorlash savollari

Idempotent metod nima? Misol keltiring.

Takroriy yuborilganda server holati bir xil bo‘ladigan metod: GET, PUT, DELETE.

Buyurtma yaratildi — qaysi status va sarlavha?

201 Created va Location: /api/v1/orders/42.

Qoldiq yetarli emas — qaysi status?

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.

Offset sahifalashning kamchiligi?

Katta jadvalda COUNT va OFFSET sekin, yangi yozuvlar qo‘shilsa sahifalar siljiydi.

RFC 7807 media turi qanday?

application/problem+json.

JWT ning uch qismi?

header, payload, signature — base64url, nuqta bilan ajratilgan.

Scribe hujjatini qanday yangilaymiz?

php artisan scribe:generate — har bir API o‘zgarishidan keyin.

Chiqish chiptasi

  1. OmborPro dagi buyurtmani bekor qilish uchun endpoint, metod va muvaffaqiyatli/xato status kodlarini yozing.
  2. JWT payloadiga nima yozish mumkin va nima mumkin emas — har biriga bitta misol.
  3. Bugungi mavzudan sizning jamoa loyihangiz API sida birinchi navbatda nimani o‘zgartirasiz?