Параметры API-запроса — это пары ключ-значение, которые добавляются к URL-адресу запроса API для отправки дополнительной информации на сервер. Они позволяют клиентам (например, веб-браузерам или приложениям) указывать определенные критерии или передавать данные при отправке запроса на сервер.

Параметры запроса добавляются в конец URL-адреса после вопросительного знака (?). Каждый параметр представляет собой пару ключ-значение, где ключ и значение разделены знаком равенства (=). Если имеется несколько параметров запроса, они разделяются амперсандом (&).

Как используются параметры запроса:
Фильтрация данных. Клиенты могут использовать параметры запроса для фильтрации нужных им данных. Например, ?category=books может указать серверу возвращать только элементы из категории «книги».

Разбиение на страницы: параметры запроса часто используются для разбиения на страницы в запросах API, позволяя клиенту указать, какую страницу результатов следует получить и сколько элементов на странице. Пример: ?page=2&limit=10.

Сортировка и упорядочение. Параметры запроса можно использовать для указания способа сортировки данных. Например, ?sort=price&order=asc может указать серверу возвращать товары, отсортированные по цене в порядке возрастания.

Передача условий поиска: API часто используют параметры запроса, чтобы клиенты могли искать данные. Например, ?search=laptop можно использовать для поиска всех продуктов, соответствующих запросу «ноутбук».

Параметры запроса очень гибки и могут использоваться по-разному, в зависимости от того, как спроектирован API. Они обеспечивают динамическое взаимодействие между клиентом и сервером, упрощая запрос индивидуальных данных.

1. Обработка основных параметров запроса Этот обработчик API демонстрирует, как извлекать и использовать параметры запроса для возврата персонализированного приветствия.

// pages/api/greet.js

export default function handler(req, res) {
  const { name } = req.query; // Get the 'name' query parameter
  const greeting = name ? `Hello, ${name}!` : 'Hello, stranger!';

  res.status(200).json({ message: greeting });
}

Пример использования:
/api/greet?name=Джон вернет { "message": "Привет, Джон!" }
/api/greet вернет { "message": "Привет, незнакомец!" }

1. Несколько параметров запроса В этом примере обработчик API извлекает несколько параметров запроса и возвращает форматированный ответ на основе вводимых пользователем данных.

// pages/api/user.js

export default function handler(req, res) {
  const { name, age } = req.query; // Get 'name' and 'age' query parameters

  if (!name || !age) {
    res.status(400).json({ error: 'Name and age are required' });
    return;
  }

  res.status(200).json({ message: `User ${name} is ${age} years old.` });
}

Пример использования:
/api/user?name=Jane&age=28 вернет { "message": "Пользователю Джейн 28 лет." }
/api/user?name=Джейн вернет { "ошибка": "Укажите имя и возраст" }

1. Необязательные параметры запроса со значениями по умолчанию В этом примере показано, как обрабатывать необязательные параметры запроса, предоставляя значения по умолчанию, если параметры отсутствуют.

// pages/api/score.js

export default function handler(req, res) {
  const { player = 'Anonymous', score = '0' } = req.query; // Default values if missing

  res.status(200).json({ message: `${player} scored ${score} points!` });
}

Пример использования:
/api/score?player=Alex&score=100 вернет { "message": "Алекс набрал 100 очков!" }
/api/score вернет { "message": "Аноним набрал 0 очков!" }

1. Обработка массивов в параметрах запроса Next.js позволяет передавать параметры запроса в виде массивов. В этом примере показано, как обрабатывать массив значений.

// pages/api/tags.js

export default function handler(req, res) {
  const { tags } = req.query; // Get 'tags' query parameter (array)

  if (!tags) {
    res.status(400).json({ error: 'Tags are required' });
    return;
  }

  res.status(200).json({ message: `You have selected these tags: ${tags.join(', ')}` });
}

Пример использования:
/api/tags?tags=javascript&tags=react вернет { "message": "Вы выбрали эти теги: javascript, React" }
/api/tags вернет { "ошибка": "Теги обязательны" }

1. Разбиение на страницы с параметрами запроса Этот обработчик демонстрирует, как реализовать нумерацию страниц с использованием параметров запроса для страницы и лимита.

// pages/api/items.js

export default function handler(req, res) {
  const { page = 1, limit = 10 } = req.query; // Default values for page and limit
  const startIndex = (page - 1) * limit;
  const endIndex = startIndex   Number(limit);

  // Dummy data for demonstration
  const items = Array.from({ length: 100 }, (_, i) => `Item ${i   1}`);
  const paginatedItems = items.slice(startIndex, endIndex);

  res.status(200).json({
    currentPage: page,
    perPage: limit,
    items: paginatedItems,
  });
}

Пример использования:
/api/items?page=2&limit=5 вернет следующие 5 элементов, например { "items": ["Item 6", "Item 7", "Item 8", "Item 9", "Item 10"] }
/api/items (значения по умолчанию) вернет первые 10 элементов, например { "items": ["Item 1", "Item 2", ..., "Item 10"] }

Эти примеры демонстрируют гибкость использования параметров запроса в маршрутах API Next.js, охватывая общие шаблоны, такие как один или несколько параметров, необязательные значения, массивы и нумерация страниц.