Чтобы не путались ни потребители, ни разработчики.

Когда мы уже определили цели 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