Сұраныс параметрлері

Тізім эндпоинті (GET /m/{project-key}/{resource-name}) белгіленген сұраныс параметрлер жиынтығын қабылдайды. Ол әрдайым қаптамасы жоқ жай JSON массивін қайтарады — беттеу метадеректері оның орнына жауап тақырыптарында жүреді: X-Total-Count, X-Page, X-Limit және first/last/prev/next URL мекенжайларын алып жүретін Link тақырыбы (RFC 5988).

Беттеу

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 "$48.19" қайтаратын price өрісіне дұрыс сәйкес келеді — сан ретінде сүзгілеу үшін өрістің дәл пішімін білудің қажеті жоқ.

Іздеу

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 немесе одан аз жазбасы бар ресурстарда ғана жұмыс істейді. Одан жоғарыда тек беттеу жұмыс істейді — неге олай екенін және жауаптың мұны қалай білдіретінін Генерация қалай жұмыс істейді бетінен қараңыз.