Параметры запроса

Списковый эндпоинт (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 записей или меньше. Выше этого порога работает только пагинация — почему так и как ответ сообщает вам об этом, см. в разделе Как устроена генерация.