Параметрҳои дархост

Эндпоинти рӯйхат (GET /m/{project-key}/{resource-name}) маҷмӯи собити параметрҳои дархостро қабул мекунад. Он ҳамеша массиви холиси JSON бармегардонад — бидуни объекти печонанда — бо метаддодаҳои саҳифабандӣ дар ҳедерҳои ҷавоб: X-Total-Count, X-Page, X-Limit ва ҳедери Link (RFC 5988), ки URL-ҳои first/last/prev/next-ро дар бар мегирад.

Саҳифабандӣ

page (пешфарз 1) ва limit (пешфарз 10, ҳадди аксар 100 — дархост барои бештар танҳо 100-ро мегирад, рад намешавад).

curl "https://mocklab.dev/m/demo7k2m9x/products?page=2&limit=20"

Тартиб

sort номи майдонро мегӯяд; order asc (пешфарз) ё desc аст.

curl "https://mocklab.dev/m/demo7k2m9x/products?sort=price&order=desc"

Тартибдиҳӣ устувор аст — сабтҳо бо арзишҳои баробар дар майдони тартиб тартиби нисбии худро нигоҳ медоранд — ва ҳатто барои майдони форматшуда ба монанди price рақамро дарк мекунад: тартибдиҳӣ бо price 48.19-ро дуруст бо 120.00 муқоиса мекунад, на ҳамчун матн.

Филтр

Ҳар параметри дархосте, ки яке аз номҳои захирашудаи боло (page, limit, sort, order, search) нест, ҳамчун филтр дар майдони бо ҳамон ном баррасӣ мешавад. field=value-и одӣ мувофиқати дақиқ аст; чор суффикс боқимондаро фаро мегиранд:

curl "https://mocklab.dev/m/demo7k2m9x/products?inStock=true&price_gte=20&price_lte=100"

_gte/_lte пеш аз муқоиса аломати асъор ё формати дигарро мебароранд, пас price_gte=20 дуруст бо майдони price-е, ки "$48.19" бармегардонад, мувофиқат мекунад — шумо барои филтр кардани он ба таври рақамӣ намебояд формати дақиқи майдонро донед.

Ҷустуҷӯ

search мувофиқат мекунад, агар арзиши ягон майдон истилоҳро дар бар гирад, бидуни ҳисси ҳарф — роҳи зуд барои ёфтани сабт бидуни донистани он, ки дар кадом майдон аст.

curl "https://mocklab.dev/m/demo7k2m9x/products?search=vivid"

Параметрҳои нодуруст

page, limit ва order се параметри ягонае мебошанд, ки шакли қатъӣ ва санҷидашаванда доранд: page ва limit бояд рақамҳои мусбати бутун бошанд, order бояд дақиқан asc ё desc бошад. Чизи дигаре фиристед — дархост ҳаргиз ба додаҳои шумо намерасад: он фавран бо хатои 422 Validation failed ва бадане, ки дақиқ мегӯяд кадом параметр нодуруст буд, қатъ мешавад. Ҳама чизи дигар — sort, search ва ҳар филтр — луғати собите барои санҷиш надорад, пас хатои имлоӣ дар он ҷо (масалан, филтр дар номи майдоне, ки вуҷуд надорад) хато ҳисоб намешавад; он танҳо ҳеҷ чиз пайдо намекунад, зеро сервер роҳи фарқ кардани "номи нодурусти майдон"-ро аз "майдоне, ки воқеан сабти мувофиқ надорад" надорад.

Якҷоя кардани параметрҳо

Ҳамаи болоӣ дар як дархост якҷоя мешаванд — филтр, ҷустуҷӯ, тартиб ва саҳифабандиро якҷоя:

const params = new URLSearchParams({
  inStock: "true",
  price_gte: "20",
  sort: "price",
  order: "asc",
  page: "1",
  limit: "20",
});
const response = await fetch(`https://mocklab.dev/m/demo7k2m9x/products?${params}`);
const products = await response.json();
const totalCount = response.headers.get("X-Total-Count");

import { useQuery } from "@tanstack/react-query";

function InStockProducts({ page }) {
  const { data: products } = useQuery({
    queryKey: ["products", "in-stock", page],
    queryFn: async () => {
      const params = new URLSearchParams({
        inStock: "true",
        sort: "price",
        order: "asc",
        page: String(page),
        limit: "20",
      });
      const res = await fetch(`https://mocklab.dev/m/demo7k2m9x/products?${params}`);
      return res.json();
    },
  });

  return (
    <ul>
      {products?.map((product) => (
        <li key={product.id}>{product.title}</li>
      ))}
    </ul>
  );
}

Як маҳдудияте, ки арзиши пешакӣ донистан дорад: филтр, ҷустуҷӯ ва тартибдиҳӣ танҳо дар захираҳое, ки 10,000 сабт ё камтар доранд, кор мекунанд. Аз он зиёдтар, танҳо саҳифабандӣ кор мекунад — сабабашро ва он ки ҷавоб чӣ гуна ба шумо мегӯяд, ки ин рӯй додааст, дар Тарзи кори сохтан бинед.