API. Проектирование параметров: от концепции ➡️ к реальным запросам

Когда мы описываем ресурс, хочется просто «вынести наружу» все его поля. Но API‑дизайн требует дисциплины: параметр должен передавать только то, что реально нужно клиенту — и только то, что он способен прислать. Смотрим, как это работает на примере создания‑обновления‑замены товара.

➡️ Один ресурс — разные представления
Концепция товара хранит всё: reference, name, price, dateAdded, supplier

Запрос на  добавление:
🔚клиент не знает reference и dateAdded — их генерирует сервер.
🔚supplier упрощаем до  supplierReference: строку легко взять со штрих‑кода или из другого эндпойнта.

Запрос на  обновление/замену:
🔚reference уже в  URL  /products/{reference} — в теле повторять нечего.
🔚всё остальное — только то, что реально меняем.
 Итог: одна и та же сущность представлена по‑разному в разных контекстах.

➡️ Правило минимального набора

Параметр должен предоставлять необходимые данные, но не более того.

🔚Убираем всё, что рассчитывается или хранится сервером.
🔚Стреляем по воде: сложные вложенные объекты → ссылки (supplierReference).
🔚Если поле не нужно для выполнения операции — безжалостно вон.

➡️ Чек‑лист Откуда берётся каждое свойство?
вопрос → действие

➖ Клиент уже знает значение? → Берём как есть.
➖ Можно вытянуть из свежего ответа API? → Расширяем нужный эндпойнт.
➖ Данные генерирует сервер? → Убираем из  тела запроса.
➖ Поле всё‑таки нужно, но  источника нет → Добавляем недостающую цель/эндпойнт.
Так мы гарантируем, что клиент всегда способен составить запрос без магии и угадывания.

➡️ Параметр free‑query: свободный текстовый поиск
Это строка фильтра для поиска: имя, часть описания или ссылка.
Тот же принцип: удобство клиента > идеальная модель. Главное — понятно задокументировать, как именно сервер трактует ввод.

➡️ Помним о  постоянном совершенствовании
При переходе от концепции к параметрам нередко всплывают пробелы: А  как клиент узнает supplierReference?.
Это нормально:
🔚выявили дыру
🔚добавили недостающий эндпойнт или уточнили существующий
🔚пересмотрели параметры
Так слой за слоем API становится стройнее и  дружелюбнее.

Оптимальный параметр — это не короткая копия ответа, а точно выверенный набор данных, который клиент способен предоставить здесь и сейчас. Режем лишнее, генерируем серверное, даём ссылки вместо вложенностей и всегда задаём вопрос: Откуда у клиента эти данные?
➡️  Следуйте чек‑листу, и ваши эндпойнты будут простыми, предсказуемыми и приятными в работе.

PS

Когда вы решите использовать определенный тип API, важно знать, что иногда можно столкнуться с ограничениями. Вы можете изо всех сил пытаться найти представление цели, которая соответствует выбранной модели API, или получить представление, соответствующее модели, но оно будет не таким удобным для пользователя, как вы ожидали. Иногда идеального представления не существует, поэтому вам, как проектировщику API, придется искать компромисс.

#навыкАналитика #REST #api #чек_лист #проектирование #IT