Какие параметры передать в GET-запрос для фильтрации списка книг по автору и жанру?

Что проверяют

Умеете ли вы описать контракт так, чтобы разработчику не пришлось додумывать: как называются параметры, что будет с несколькими значениями, пустым результатом и кириллицей в URL. Следом часто просят показать это в спецификации OpenAPI и добавить пагинацию.

Как отвечать

Базовый вариант: GET /books?author_id=42&genre=fantasy. Фильтры это query-параметры, ресурс остаётся тем же списком книг.

• идентификаторы вместо имён: фильтр по author_id надёжнее строки «Толстой». Однофамильцев много, написание расходится. Поиск по имени лучше вынести в отдельный параметр вроде q;
• жанр кодом: значение из справочника, fantasy или genre_id, а не свободный текст;
• несколько значений: genre=fantasy&genre=detective или genre=fantasy,detective. Выбирают один формат и фиксируют в спецификации, в OpenAPI это style: form и explode;
• логика: между разными параметрами И, внутри одного параметра ИЛИ. Прописывается явно;
• пагинация и сортировка: limit и offset или курсор, sort=-published_at, плюс максимальный limit, чтобы никто не выгрузил весь каталог одним запросом;
• кодировка: кириллица и пробелы в значениях передаются через percent-encoding в UTF-8, «Толстой» превращается в %D0%A2%D0%BE....

Ответ: 200 и массив, плюс общее число или ссылка на следующую страницу. Если книг нет, это всё равно 200 с пустым массивом. Некорректное значение, например limit=abc, даёт 400 или 422 с понятным текстом ошибки.

Где спотыкаются

Отвечают 404, когда по фильтру ничего не нашлось. Ресурс /books существует, пустой список это нормальный результат.

Предлагают передать фильтры в теле GET. Спецификация HTTP не задаёт смысла телу у GET, прокси и клиенты его отбрасывают. Для сложных фильтров делают POST /books/search.

Не описывают поведение при отсутствии параметров и при нескольких значениях. Разработчик и тестировщик понимают это по-разному, и расхождение всплывает уже в проде.