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