Как спроектировать данные для API, чтобы не путались ни потребители, ни разработчики
Когда мы уже определили цели API, ресурсы и действия — приходит время спроектировать сами данные: те, что возвращаются в ответе или приходят в параметрах.
Тут легко скатиться в «выкатим всё, что есть» или «а вдруг пригодится». Но у хорошего API есть принципы.
➖ Проектируем данные человечно и понятно:
1️⃣ Начинай с концепции
Ресурс — это отражение бизнес-сущности.
Например, товар. Перечисли его свойства:reference, name, price, dateAdded, unavailable, warehouses, description, supplier и спроси себя:
🔚 Касаются ли эти свойства потребителя?
🔚 Все ли они действительно нужны?
🔚 Поймёт ли потребитель, о чём речь?
2️⃣ Мысленно отфильтруй лишнее
На этапе проектирования часто видно:
🔚 warehouses — список складов. Внутренний атрибут, не дающий ценности покупателю, убираем.
🔚 unavailable — звучит туманно. Когда, почему, насколько? Переименовываем в definitelyOutOfStock ✅ — чётче не придумаешь.
🔚 r, p — разработчику понятно, потребителю — нет. r это reference, p — price или product? Используем говорящие имена.
✂️ Убираем, переименовываем, упрощаем.
3️⃣ Для каждого свойства фиксируем 4 вещи:
🔚 Имя — понятно ли оно само по себе?
🔚 Тип — string, number, date и т.п. (переносимые типы❗️)
🔚 Обязательность — должно ли быть всегда?
🔚 Описание — помогает понять смысл, если имя не спасает
Пример:
{
"reference": "R123-456",
"name": "product",
"price": 9.99,
"dateAdded": "2018-01-02",
"definitelyOutOfStock": false,
"supplier": {
"reference": "S789",
"name": "supplier"
}
}
🧱 Всё это превращается в структуру ресурса — как в таблице на картинке. А дальше — уже можно использовать её и в ответах, и в параметрах API.
4️⃣ Не забывай про потребителя
Хорошее API не должно рассказывать, как оно устроено. Оно должно быть удобно читаемо и логично для того, кто им пользуется.
➡️Совет: выбирай такие имена и структуры, которые одинаково понятны тебе, разработчику фронта и случайному читателю вашей документации в пятницу вечером.
✅ Это и есть проектирование данных: не только про JSON, но про смысл.
#навыкАналитика #чек_лист #REST #api #проектирование #IT
Когда мы уже определили цели API, ресурсы и действия — приходит время спроектировать сами данные: те, что возвращаются в ответе или приходят в параметрах.
Тут легко скатиться в «выкатим всё, что есть» или «а вдруг пригодится». Но у хорошего API есть принципы.
➖ Проектируем данные человечно и понятно:
1️⃣ Начинай с концепции
Ресурс — это отражение бизнес-сущности.
Например, товар. Перечисли его свойства:reference, name, price, dateAdded, unavailable, warehouses, description, supplier и спроси себя:
🔚 Касаются ли эти свойства потребителя?
🔚 Все ли они действительно нужны?
🔚 Поймёт ли потребитель, о чём речь?
2️⃣ Мысленно отфильтруй лишнее
На этапе проектирования часто видно:
🔚 warehouses — список складов. Внутренний атрибут, не дающий ценности покупателю, убираем.
🔚 unavailable — звучит туманно. Когда, почему, насколько? Переименовываем в definitelyOutOfStock ✅ — чётче не придумаешь.
🔚 r, p — разработчику понятно, потребителю — нет. r это reference, p — price или product? Используем говорящие имена.
✂️ Убираем, переименовываем, упрощаем.
3️⃣ Для каждого свойства фиксируем 4 вещи:
🔚 Имя — понятно ли оно само по себе?
🔚 Тип — string, number, date и т.п. (переносимые типы❗️)
🔚 Обязательность — должно ли быть всегда?
🔚 Описание — помогает понять смысл, если имя не спасает
Пример:
{
"reference": "R123-456",
"name": "product",
"price": 9.99,
"dateAdded": "2018-01-02",
"definitelyOutOfStock": false,
"supplier": {
"reference": "S789",
"name": "supplier"
}
}
🧱 Всё это превращается в структуру ресурса — как в таблице на картинке. А дальше — уже можно использовать её и в ответах, и в параметрах API.
4️⃣ Не забывай про потребителя
Хорошее API не должно рассказывать, как оно устроено. Оно должно быть удобно читаемо и логично для того, кто им пользуется.
➡️Совет: выбирай такие имена и структуры, которые одинаково понятны тебе, разработчику фронта и случайному читателю вашей документации в пятницу вечером.
✅ Это и есть проектирование данных: не только про JSON, но про смысл.
#навыкАналитика #чек_лист #REST #api #проектирование #IT