Проектирование данных для API — часть 2
Контекст, параметры и здравый смысл 🔍
В предыдущем посте мы говорили, как спроектировать данные для API, чтобы структура была понятной и ориентированной на потребителя. Но на этом история не заканчивается.
➡️ Одна и та же концепция (например, «товар») может использоваться: ➖в поиске (каталог товаров), ➖при добавлении в каталог, ➖при получении конкретного товара. В каждом из этих случаев ответ может выглядеть по-разному.
❌ Ответ ≠ ресурс 1 к 1
➡️ Смотри на схему
➡️ Ресурс «товар» — это вся сущность со всеми полями. Но: ➖ В поиске важны только reference, name, price, supplierName — остальное шум. ➖ При добавлении и получении — наоборот, нужен полный объект. Проектируя ответ, мы не обязаны возвращать всё. Мы подстраиваем структуру под конкретный сценарий — и тем самым делаем API понятным, лёгким и быстрым.
❌ А что насчёт параметров?
➡️ Параметры — это данные, которые потребитель отправляет в API. И да, их тоже надо проектировать с умом (см. схему): ➖ При добавлении товара не нужно передавать reference или dateAdded — они генерируются на сервере. ➖ Но при обновлении или замене — reference уже обязателен, т.к. это ссылка на конкретный товар.
➡️ Ещё пример: объект supplier в параметрах можно сократить до supplierReference, потому что всю остальную информацию сервер может подтянуть сам. Так API становится легче и устойчивее.
☑️ Проверка: потребитель точно может это передать?
Вот где всё проверяется на прочность (см. схему): ➡️ Для каждого параметра спроси себя: ➖ Может ли потребитель ввести это сам? ➖ Получает ли он это из другого ответа? ➖ Присутствует ли это в цели API?
➡️ Если нет — либо добавляем цель, либо пересматриваем, нужно ли вообще это поле. Всё, что не может быть передано потребителем — кандидат на удаление из параметров.
➖ И да — параметры запроса, как free-query в поиске, проектируются так же: с прицелом на пользователя. Это просто строка, а не сложный фильтр с 20 ключами. Простота рулит.
➡️ Главное: ➖ Ответы = адаптированные представления концепции. ➖ Параметры = только то, что реально может предоставить потребитель. ➖ API = не сериализация модели, а интерфейс между людьми и системами.
Проектирование — это не только про поля и типы. Это про понимание контекста, вопросы без страха и удаление всего лишнего.
