REST API loyihalash
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.
Bu ma’ruza oxirida siz quyidagilarni bajara olasiz...
/api/v1 resurslar daraxti, sahifalash va filtrlash parametrlariniRoute::apiResource, API Resource va Form Request niper_page, ma’lumot sizib chiqishiREST resurslari va HTTP semantikasi
Resurs, URI va ko‘rinish
Resurs
products, orders/42, orders/42/items.Ko‘rinish
Stateless
Authorization sarlavhasida keladi.Amal-endpoint
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 nimani anglatadi?
| 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.Qaysi holatda qaysi kod?
| 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.1-bo‘lim yakuni: REST resurslari va HTTP semantikasi
/api/createOrder yaxshi URI emas?POST va PUT ning idempotentlik bo‘yicha farqi nimada?1-topshiriq: HTTP metodining xossalari
API shlyuzi (gateway) takroriy yuborishga ruxsat berishdan oldin metod xossalarini bilishi kerak. Metod nomi berilgan (katta-kichik harf farqi yo‘q). GET, HEAD, OPTIONS — xavfsiz va idempotent; PUT, DELETE — xavfsiz emas, lekin idempotent; POST, PATCH — ikkalasi ham emas. Boshqa har qanday nom (bo‘sh satr ham) — InvalidArgumentException.
Imzo: function metod_xossasi(string $method): array
Qaytaradi: ['safe' => bool, 'idempotent' => bool] — kalitlar aynan shu tartibda.
metod_xossasi('GET'){"safe":true,"idempotent":true}Laravel’da API: marshrutlar, controller va API Resource
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']); }); });
$ 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/api + /v1 — URL da versiya; nomlar v1.products.indexapi guard (JWT) — tokensiz so‘rov 401 oladicreate/edit yo‘qOrderService ni chaqiradiIngichka 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)); } }
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/16per_page chegarasi — 1 000 000 yozuvli javobdan himoyalinks.next ichida saqlanadiLocation ni biz qo‘shamizProductResource — 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)], ]; } }
{"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"}}}deleted_at, ichki ustunlar chiqmaydidecimal:2 cast satr qaytaradi — float yo‘qdata ichiga o‘raydiMijoz 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}
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", ...}}2-bo‘lim yakuni: Laravel’da API: marshrutlar, controller va API Resource
Route::apiResource qaysi metodlarni yaratadi va Route::resource dan farqi nimada?Versiyalash, sahifalash va filtrlash
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_idendi 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
detailmatnini aniqlashtirish - unumdorlikni oshirish, indeks qo‘shish
Sunset: Sat, 01 May 2027 00:00:00 GMT sarlavhasi.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;
{"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}to = 93, 100 emasfrom va to — null (Laravel ham shunday)last_page = 1Sahifalangan 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 } }
cursorPaginate() da meta: path, per_page, next_cursor, prev_cursor (total va last_page yo‘q — COUNT(*) bajarilmaydi)
ProductResource orqali)COUNT(*) bilanRuxsat 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)) ); }
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 → 422Stringable qaytaradi; toString() — oddiy satrper_page jim kesilmaydi, 422 bilan rad etiladi3-bo‘lim yakuni: Versiyalash, sahifalash va filtrlash
price maydonini satrdan songa o‘zgartirish nima uchun yangi versiya talab qiladi?sort parametrini oq ro‘yxat bilan tekshirish kerak?2-topshiriq: Sahifalash meta ma’lumoti
Laravel paginate() javobidagi meta blokini hisoblang. Jami yozuvlar $total, sahifa hajmi $perPage va joriy sahifa $page berilgan. last_page — kamida 1. from — sahifadagi birinchi yozuv tartib raqami (1 dan), to — oxirgisi; agar sahifada yozuv bo‘lmasa (bo‘sh ro‘yxat yoki $page > last_page), ikkalasi ham null. $perPage 1–100 oralig‘ida bo‘lmasa, $page < 1 yoki $total < 0 bo‘lsa — InvalidArgumentException.
Imzo: function sahifa_meta(int $total, int $perPage, int $page): array
Qaytaradi: ['current_page' => int, 'per_page' => int, 'total' => int, 'last_page' => int, 'from' => ?int, 'to' => ?int] — shu tartibda.
sahifa_meta(93, 20, 1)
{"current_page":1,"per_page":20,"total":93,"last_page":5,"from":1,"to":20}Xatolar formati: Problem Details (RFC 7807)
Problem Details maydonlari
Content-Type: application/problem+json va beshta standart maydon.type va title
.../problems/insufficient-stock, “Qoldiq yetarli emas”.status
409 — proxy kodni o‘zgartirsa ham asl qiymat saqlanadi.detail va instance
/api/v1/orders/42/confirm.Kengaytmalar
errors (validatsiya), available, trace_id.type ga qarab qaror qiladi; detail matni o‘zgarishi mumkin, unga tayanmang.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);
{
"type": "about:blank",
"title": "Biznes-qoida buzildi",
"status": 409,
"detail": "UN-001: mavjud 3, so‘ralgan 5",
"instance": "/api/v1/orders/42/confirm"
}InsufficientStockException ham shu shartga tushadi (meros)\u2018 ga aylanmaydiLaravel 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();
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‘qYomon 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)
4-bo‘lim yakuni: Xatolar formati: Problem Details (RFC 7807)
InsufficientStockException qanday qilib controllerda try/catch siz 409 javobga aylanadi?APP_DEBUG=false bo‘lishi shart?3-topshiriq: Problem Details javobi
Ichki xato kodidan RFC 7807 javobini yasang. Ma’lum kodlar: validation (422, “Validatsiya xatosi”), not_found (404, “Resurs topilmadi”), unauthenticated (401, “Autentifikatsiya talab qilinadi”), forbidden (403, “Ruxsat yo‘q”), insufficient_stock (409, “Qoldiq yetarli emas”), invalid_transition (409, “Holat o‘tishi taqiqlangan”). Ular uchun type = https://omborpro.test/problems/ + kod (pastki chiziq - ga almashtiriladi). detail bo‘sh satr bo‘lsa, o‘rniga title yoziladi. Noma’lum kod — 500, type = about:blank, title = “Ichki xato” va detail har doim “Kutilmagan xato” (ichki xabar mijozga chiqmaydi).
Imzo: function problem(string $kod, string $detail, string $instance): array
Qaytaradi: ['type' => string, 'title' => string, 'status' => int, 'detail' => string, 'instance' => string] — shu tartibda.
problem('insufficient_stock', 'UN-001: mavjud 3, so‘ralgan 5', '/api/v1/orders/42/confirm'){"type":"https://omborpro.test/problems/insufficient-stock","title":"Qoldiq yetarli emas","status":409,"detail":"UN-001: mavjud 3, so‘ralgan 5","instance":"/api/v1/orders/42/confirm"}Autentifikatsiya: token, JWT va Sanctum
header.payload.signature
Header
{"alg":"HS256","typ":"JWT"} → eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9Payload
sub, iat, exp, jti + role. Har kim o‘qiy oladi — maxfiy ma’lumot yozilmaydi.Signature
HMAC-SHA256(header.payload, JWT_SECRET). O‘zgartirilgan payload imzodan o‘tmaydi.alg kutilganmi → imzo hash_equals → exp > hozirgi vaqt.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"; }
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
{"sub":7,"role":"menejer"}
imzo to‘g‘ri
soxta token+/ → -_, = yo‘qrole: admin ga almashtirilgan payload rad etiladiLogin: 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, ]); }
POST /api/v1/auth/login → 200
{"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3Mi...",
"token_type": "bearer", "expires_in": 3600}config/auth.php dagi 'api' => ['driver' => 'jwt', ...] guardis_active = true sharti qo‘shiladijwt.ttl daqiqada (standart 60) → sekundSanctum 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_SECRETfaqat.envda
throttle.5-bo‘lim yakuni: Autentifikatsiya: token, JWT va Sanctum
== emas, hash_equals() ishlatiladi?OpenAPI hujjatlari: Scribe va Postman
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}
Scribe → /docs (HTML hujjat), /docs.openapi (shu YAML), /docs.postman (kolleksiya)
components da tavsiflanadiController 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) { // ... }
$ 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 sarlavhasiKoddan Postman kolleksiyasigacha
O‘rnatish
composer require --dev knuckleswtf/scribe, vendor:publish --tag=scribe-configSozlash
config/scribe.php: routes → api/*, auth.enabled → Bearer, postman va openapi yoqilganIzohlash
@group, @authenticated, @queryParam, @response teglariYaratish
php artisan scribe:generate → /docs, /docs.openapi, /docs.postmanPostman
baseUrl va token muhit o‘zgaruvchilariAvtomatlash
newman run bilan kolleksiyani buyruq qatorida yugurtirishscribe:generate qayta ishga tushiriladi — hujjat koddan orqada qolmasin.6-bo‘lim yakuni: OpenAPI hujjatlari: Scribe va Postman
baseUrl, token) nima uchun kerak?Asosiy xulosalar
1Resurs — ot, metod — fe’l
GET /api/v1/products, POST /api/v1/orders/42/confirm; URI da get, create yo‘q.2Status kod — signal
Location, 204, 401/403, 404, 409 (biznes-qoida), 422 (validatsiya), 429.3API Resource — shartnoma
whenLoaded.4Versiya va sahifalash
/api/v1, buzuvchi o‘zgarish faqat yangi versiyada; per_page 1–100, cursor — katta jurnallar uchun.5Yagona xato formati
type, title, status, detail, instance; withExceptions() da markazlashgan.6JWT va hujjat
ttl; Scribe → OpenAPI + Postman kolleksiyasi.Yakunlashdan oldin sakkizta savol
whenLoaded('category') nima qiladi?7-amaliy mashg‘ulot: 5 ta PHP topshiriq va loyiha bosqichi
Authorization sarlavhasidan token
HS256 JWT yasash
Ro‘yxat so‘rovi parametrlari
JWT ni tekshirish
So‘rovlar limiti (rate limiter)
Darsni tark etishdan oldin
Javoblaringizni yozing (✎ Javob yozish) yoki qog‘ozga yozib topshiring.