Аналитик на Балтике | Неверов Станислав

Как спроектировать данные для 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

Please open Telegram to view this post

VIEW IN TELEGRAM

Please open Telegram to view this post

VIEW IN TELEGRAM

🔥4❤3👍3😁33

www.group-telegram.com/de/BalticAnalyst.com/542

640 viewsJul 3 at 06:01

Как спроектировать данные для 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"
  }
}