5.7-bob: REST API dizayni (resurslar, metodlar, status, versiyalash, best practices)

   FE'L (action) URL'da:         OT (resurs) URL'da:
  /getUsers                       GET    /users
  /createUser                     POST   /users
  /deleteUser?id=5                DELETE /users/5
  /updateUserName                 PATCH  /users/5

   Ko'plik ot:         /users (collection), /users/5 (bitta)
   Iyerarxiya:         /users/5/orders (5-foydalanuvchining buyurtmalari)
   Kichik harf, tire:  /blog-posts (camelCase/underscore emas)
   Versiya:            /api/v1/users (2.10)
   Fe'l:               /getUsers, /createOrder
   Birlik collection:  /user (ko'plik: /users)
   Kengaytma:          /users.json (Accept header — 2.13)

  PUT /users/5 — TO'LIQ almashtirish (butun obyektni yuborasiz)
    body: { ism: "Ali", email: "a@b.uz", yosh: 20 }   HAMMA maydon
     yo'q maydonlar O'CHADI (yoki default)

  PATCH /users/5 — QISMAN yangilash (faqat o'zgaradigan)
    body: { yosh: 21 }   faqat yosh
     boshqa maydonlar O'ZGARMAYDI

  Filtr:        GET /users?role=admin&active=true
  Saralash:     GET /products?sort=-price (- = kamayish), ?sort=name
  Sahifalash:   GET /posts?page=2&limit=20  (yoki ?offset=20&limit=20)
  Maydon tanlash: GET /users?fields=id,ism  (faqat kerakli maydonlar)
  Qidiruv:      GET /products?search=telefon

  Offset-based:   ?page=2&limit=20 (20–39 yozuvlar) — oddiy, lekin katta offsetda sekin
  Cursor-based:   ?cursor=abc123&limit=20 — tez, real-time uchun (oxirgi ID'dan)

{
  "data": [ ... ],
  "meta": { "page": 2, "limit": 20, "total": 145, "totalPages": 8 }
}

  GET /users/5      — 100 marta chaqiring  bir xil (idempotent )
  DELETE /users/5   — 2-marta  allaqachon yo'q (idempotent , 204 yoki 404)
  PUT /users/5      — 2-marta  bir xil holat (idempotent )
  POST /users       — 2-marta  IKKI user! (idempotent EMAS )

  1. URL path (eng keng tarqalgan):  /api/v1/users, /api/v2/users
  2. Header:                         Accept: application/vnd.api.v1+json
  3. Query:                          /users?version=1

// Muvaffaqiyat
{ "success": true, "data": { ... } }
// Ro'yxat (meta bilan — 2.8)
{ "success": true, "data": [ ... ], "meta": { ... } }
// Xato (2.12)
{ "success": false, "error": { "code": "NOT_FOUND", "message": "..." } }

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Ma'lumot noto'g'ri",
    "details": [
      { "field": "email", "message": "Email noto'g'ri" }
    ]
  }
}

  Cache-Control: max-age=3600   — 1 soat keshlansin 0.4-bob
  ETag: "abc123"                — resurs versiyasi (o'zgarmagan bo'lsa 304 — 0.4)
  If-None-Match: "abc123"       — client: shu versiyam bor; o'zgardimi?
   304 Not Modified (o'zgarmagan — body yubormaydi, tejaydi)

{
  "data": { "id": 5, "ism": "Ali" },
  "links": { "self": "/users/5", "orders": "/users/5/orders" }
}

  POST /users/5/activate        — aktivlashtirish (CRUD emas)
  POST /orders/5/cancel         — bekor qilish
  POST /auth/login              — login 5.15-bob
  POST /payments/5/refund       — qaytarish

RESURS:   ot, ko'plik — /users, /users/5, /users/5/orders
METOD:    GET (o'qish), POST (yaratish201), PUT (to'liq), PATCH (qisman), DELETE (204)
STATUS:   200/201/204  | 400/401/403/404/409/422/429 (client) | 500 (server)
QUERY:    ?role=admin (filtr) &sort=-price &page=2&limit=20 (2.7, 2.8)
VERSIYA:  /api/v1/... 2.10-bob
JAVOB:    { success, data, meta } / { success:false, error } (2.11, 2.12)

import { Router } from "express";       // (5.6)
const router = Router();

// Resurs: users (ot, ko'plik — 2.3)
router.get("/", getAllUsers);           // GET    /users — ro'yxat
router.get("/:id", getUser);            // GET    /users/5 — bitta
router.post("/", createUser);           // POST   /users — yaratish (201)
router.patch("/:id", updateUser);       // PATCH  /users/5 — qisman (2.5)
router.delete("/:id", deleteUser);      // DELETE /users/5 — o'chirish (204)

// Iyerarxik resurs (2.3)
router.get("/:id/orders", getUserOrders);   // GET /users/5/orders

export default router;
// app.use("/api/v1/users", router)   versiya bilan (2.10)

// GET — 200 yoki 404
const getUser = (req, res) => {
  const user = users.find(u => u.id === Number(req.params.id));   // (5.6)
  if (!user) {
    return res.status(404).json({ success: false, error: { code: "NOT_FOUND", message: "Foydalanuvchi topilmadi" } });   // (2.6, 2.12)
  }
  res.status(200).json({ success: true, data: user });           // (2.11)
};

// POST — 201 Created
const createUser = (req, res) => {
  const yangi = { id: nextId++, ...req.body };
  users.push(yangi);
  res.status(201).json({ success: true, data: yangi });          // 201! (2.6)
};

// DELETE — 204 No Content
const deleteUser = (req, res) => {
  users = users.filter(u => u.id !== Number(req.params.id));
  res.status(204).end();                                          // body'siz (2.6)
};

const getAllUsers = (req, res) => {
  const page = Math.max(1, Number(req.query.page) || 1);          // (5.6: query)
  const limit = Math.min(100, Number(req.query.limit) || 20);    // max 100 (DoS — 14)
  const offset = (page - 1) * limit;

  const sahifaData = users.slice(offset, offset + limit);        // (2.7-JS: slice)
  const total = users.length;

  res.json({
    success: true,
    data: sahifaData,
    meta: {                                                       // (2.8)
      page, limit, total,
      totalPages: Math.ceil(total / limit),
      hasNext: offset + limit < total,
    }
  });
};
// GET /users?page=2&limit=20

const getProducts = (req, res) => {
  let natija = [...products];                                     // nusxa (2.7-JS)

  // Filtr (2.7)
  const { category, minPrice, inStock } = req.query;
  if (category) natija = natija.filter(p => p.category === category);
  if (minPrice) natija = natija.filter(p => p.price >= Number(minPrice));
  if (inStock === "true") natija = natija.filter(p => p.stock > 0);

  // Saralash 2.7-bob: ?sort=-price (kamayish), ?sort=name (o'sish)
  const sort = req.query.sort;
  if (sort) {
    const desc = sort.startsWith("-");                            // (2.6-JS)
    const maydon = desc ? sort.slice(1) : sort;
    natija.sort((a, b) => desc ? b[maydon] - a[maydon] : a[maydon] - b[maydon]);  // (3.9)
  }

  res.json({ success: true, data: natija });
};
// GET /products?category=phone&minPrice=100&sort=-price

// PUT — TO'LIQ almashtirish (barcha maydon kerak — 2.5)
const replaceUser = (req, res) => {
  const idx = users.findIndex(u => u.id === Number(req.params.id));
  if (idx === -1) return res.status(404).json({ success: false, error: { message: "Topilmadi" } });
  const { ism, email, yosh } = req.body;                         // hamma maydon
  if (!ism || !email) return res.status(400).json({ success: false, error: { message: "Barcha maydon kerak" } });
  users[idx] = { id: users[idx].id, ism, email, yosh };          // TO'LIQ almashtir
  res.json({ success: true, data: users[idx] });
};

// PATCH — QISMAN (faqat berilgan maydonlar — 2.5)
const updateUser = (req, res) => {
  const user = users.find(u => u.id === Number(req.params.id));
  if (!user) return res.status(404).json({ success: false, error: { message: "Topilmadi" } });
  Object.assign(user, req.body);                                 // faqat berilganlar (2.8-JS)
  res.json({ success: true, data: user });
};

import express from "express";
import usersV1 from "./routes/v1/users.js";
import usersV2 from "./routes/v2/users.js";

const app = express();
app.use(express.json());                                          // (5.6)

app.use("/api/v1/users", usersV1);     // eski (qo'llab-quvvatlanadi)
app.use("/api/v2/users", usersV2);     // yangi (breaking change — 4.5)
// v1 client'lar buzilmaydi; yangi client'lar v2 (2.10)

// Javob helper'lari (izchillik — 2.11)
const ok = (res, data, status = 200) => res.status(status).json({ success: true, data });
const fail = (res, status, code, message, details) =>
  res.status(status).json({ success: false, error: { code, message, ...(details && { details }) } });

// Ishlatish
const getUser = (req, res) => {
  const user = users.find(u => u.id === Number(req.params.id));
  if (!user) return fail(res, 404, "NOT_FOUND", "Foydalanuvchi topilmadi");   // (2.12)
  ok(res, user);                                                              // (2.11)
};
const createUser = (req, res) => {
  if (!req.body.email) return fail(res, 400, "VALIDATION", "Email kerak");
  const yangi = { id: nextId++, ...req.body };
  users.push(yangi);
  ok(res, yangi, 201);                                                        // 201
};

// Iyerarxik: foydalanuvchining buyurtmalari (2.3)
router.get("/users/:userId/orders", (req, res) => {
  const orders = barchaBuyurtmalar.filter(o => o.userId === Number(req.params.userId));
  res.json({ success: true, data: orders });
});

// Amal-asoslangan (CRUD emas — 2.16)
router.post("/orders/:id/cancel", (req, res) => {        // bekor qilish
  const order = topBuyurtma(req.params.id);
  if (order.status === "shipped") {
    return res.status(409).json({ success: false, error: { message: "Yuborilgan buyurtma bekor qilinmaydi" } });  // 409 Conflict (2.6)
  }
  order.status = "cancelled";
  res.json({ success: true, data: order });
});

import crypto from "node:crypto";       // (5.3)

const getUser = (req, res) => {
  const user = users.find(u => u.id === Number(req.params.id));
  if (!user) return res.status(404).end();

  const etag = crypto.createHash("md5").update(JSON.stringify(user)).digest("hex");  // (5.3: hash)
  res.set("ETag", etag);                                          // (2.14)

  if (req.headers["if-none-match"] === etag) {                    // o'zgarmagan?
    return res.status(304).end();                                 // 304 — body yo'q (tejaydi — 0.4)
  }
  res.json({ success: true, data: user });
};

// controllers/productController.js (5.6: qatlamli)
const products = [];
let nextId = 1;

// GET /products — filtr + sort + pagination (2.7, 2.8)
export const list = (req, res) => {
  let natija = [...products];
  if (req.query.category) natija = natija.filter(p => p.category === req.query.category);
  if (req.query.sort) {
    const desc = req.query.sort.startsWith("-");
    const m = desc ? req.query.sort.slice(1) : req.query.sort;
    natija.sort((a, b) => (desc ? b[m] - a[m] : a[m] - b[m]));
  }
  const page = Number(req.query.page) || 1, limit = Math.min(100, Number(req.query.limit) || 20);
  const data = natija.slice((page - 1) * limit, page * limit);
  res.json({ success: true, data, meta: { page, limit, total: natija.length } });
};

// GET /products/:id (2.6)
export const getOne = (req, res) => {
  const p = products.find(x => x.id === Number(req.params.id));
  if (!p) return res.status(404).json({ success: false, error: { code: "NOT_FOUND", message: "Topilmadi" } });
  res.json({ success: true, data: p });
};

// POST /products (2.6: 201)
export const create = (req, res) => {
  const { nom, price } = req.body;
  if (!nom || price == null) return res.status(400).json({ success: false, error: { code: "VALIDATION", message: "nom va price kerak" } });
  const yangi = { id: nextId++, nom, price, createdAt: new Date().toISOString() };
  products.push(yangi);
  res.status(201).json({ success: true, data: yangi });
};

 POST /createUser, GET /getUserById?id=5
 POST /users, GET /users/5 (metod fe'l, URL ot — 2.2)

//  hammasi 200 (xato ham 200 bilan)
res.json({ error: "topilmadi" });   // status 200!

//  to'g'ri status (2.6)
res.status(404).json({ success: false, error: {...} });

 /users/admin/page/2  (path'da filtr)
 /users?role=admin&page=2 (query'da — 2.7)

//  har endpoint har xil shakl (frontend qiynaladi)
res.json(users);  // bir joyda massiv
res.json({ result: user });  // boshqa joyda obyekt

//  izchil (2.11)
res.json({ success: true, data: ... });

 /api/users (versiyasiz)  o'zgarish eski client'larni buzadi
 /api/v1/users 2.10-bob  v2 chiqarib, v1 saqlanadi