Проектирование данных для API — часть 2: контекст, параметры и здравый смысл 🔍
В предыдущем посте мы говорили, как спроектировать данные для API, чтобы структура была понятной и ориентированной на потребителя. Но на этом история не заканчивается.
➡️Одна и та же концепция (например, «товар») может использоваться: 🔚в поиске (каталог товаров), 🔚при добавлении в каталог, 🔚при получении конкретного товара. В каждом из этих случаев ответ может выглядеть по-разному.
❌ Ответ ≠ ресурс 1 к 1
➡️Смотри на схему
➡️Ресурс «товар» — это вся сущность со всеми полями. Но: 🔚В поиске важны только reference, name, price, supplierName — остальное шум. 🔚При добавлении и получении — наоборот, нужен полный объект. Проектируя ответ, мы не обязаны возвращать всё. Мы подстраиваем структуру под конкретный сценарий — и тем самым делаем API понятным, лёгким и быстрым.
❌ А что насчёт параметров?
➡️Параметры — это данные, которые потребитель отправляет в API. И да, их тоже надо проектировать с умом (см. схему): 🔚При добавлении товара не нужно передавать reference или dateAdded — они генерируются на сервере. 🔚Но при обновлении или замене — reference уже обязателен, т.к. это ссылка на конкретный товар.
💡 Ещё пример: объект supplier в параметрах можно сократить до supplierReference, потому что всю остальную информацию сервер может подтянуть сам. Так API становится легче и устойчивее.
✅ Проверка: потребитель точно может это передать?
Вот где всё проверяется на прочность (см. схему): ➡️ Для каждого параметра спроси себя: 🔚Может ли потребитель ввести это сам? 🔚Получает ли он это из другого ответа? 🔚Присутствует ли это в цели API?
➡️ Если нет — либо добавляем цель, либо пересматриваем, нужно ли вообще это поле. Всё, что не может быть передано потребителем — кандидат на удаление из параметров.
💡 И да — параметры запроса, как free-query в поиске, проектируются так же: с прицелом на пользователя. Это просто строка, а не сложный фильтр с 20 ключами. Простота рулит.
➡️Главное: 🔚Ответы = адаптированные представления концепции. 🔚Параметры = только то, что реально может предоставить потребитель. 🔚API = не сериализация модели, а интерфейс между людьми и системами.
Проектирование — это не только про поля и типы. Это про понимание контекста, вопросы без страха и удаление всего лишнего.
Проектирование данных для API — часть 2: контекст, параметры и здравый смысл 🔍
В предыдущем посте мы говорили, как спроектировать данные для API, чтобы структура была понятной и ориентированной на потребителя. Но на этом история не заканчивается.
➡️Одна и та же концепция (например, «товар») может использоваться: 🔚в поиске (каталог товаров), 🔚при добавлении в каталог, 🔚при получении конкретного товара. В каждом из этих случаев ответ может выглядеть по-разному.
❌ Ответ ≠ ресурс 1 к 1
➡️Смотри на схему
➡️Ресурс «товар» — это вся сущность со всеми полями. Но: 🔚В поиске важны только reference, name, price, supplierName — остальное шум. 🔚При добавлении и получении — наоборот, нужен полный объект. Проектируя ответ, мы не обязаны возвращать всё. Мы подстраиваем структуру под конкретный сценарий — и тем самым делаем API понятным, лёгким и быстрым.
❌ А что насчёт параметров?
➡️Параметры — это данные, которые потребитель отправляет в API. И да, их тоже надо проектировать с умом (см. схему): 🔚При добавлении товара не нужно передавать reference или dateAdded — они генерируются на сервере. 🔚Но при обновлении или замене — reference уже обязателен, т.к. это ссылка на конкретный товар.
💡 Ещё пример: объект supplier в параметрах можно сократить до supplierReference, потому что всю остальную информацию сервер может подтянуть сам. Так API становится легче и устойчивее.
✅ Проверка: потребитель точно может это передать?
Вот где всё проверяется на прочность (см. схему): ➡️ Для каждого параметра спроси себя: 🔚Может ли потребитель ввести это сам? 🔚Получает ли он это из другого ответа? 🔚Присутствует ли это в цели API?
➡️ Если нет — либо добавляем цель, либо пересматриваем, нужно ли вообще это поле. Всё, что не может быть передано потребителем — кандидат на удаление из параметров.
💡 И да — параметры запроса, как free-query в поиске, проектируются так же: с прицелом на пользователя. Это просто строка, а не сложный фильтр с 20 ключами. Простота рулит.
➡️Главное: 🔚Ответы = адаптированные представления концепции. 🔚Параметры = только то, что реально может предоставить потребитель. 🔚API = не сериализация модели, а интерфейс между людьми и системами.
Проектирование — это не только про поля и типы. Это про понимание контекста, вопросы без страха и удаление всего лишнего.
"This time we received the coordinates of enemy vehicles marked 'V' in Kyiv region," it added. Meanwhile, a completely redesigned attachment menu appears when sending multiple photos or vides. Users can tap "X selected" (X being the number of items) at the top of the panel to preview how the album will look in the chat when it's sent, as well as rearrange or remove selected media. In the past, it was noticed that through bulk SMSes, investors were induced to invest in or purchase the stocks of certain listed companies. For tech stocks, “the main thing is yields,” Essaye said. The S&P 500 fell 1.3% to 4,204.36, and the Dow Jones Industrial Average was down 0.7% to 32,943.33. The Dow posted a fifth straight weekly loss — its longest losing streak since 2019. The Nasdaq Composite tumbled 2.2% to 12,843.81. Though all three indexes opened in the green, stocks took a turn after a new report showed U.S. consumer sentiment deteriorated more than expected in early March as consumers' inflation expectations soared to the highest since 1981.
from us
