Когда мы проектируем JSON для API запросов или ответов, важно понимать, что он не берётся «с потолка».
У него всегда есть два ориентира 👇
1️⃣ База данных (БД) — источник данных
👉 Показывает, какие параметры физически хранятся в системе
👉 У каждого JSON-объекта есть ключевая таблица (основной объект) и связанные по внешним ключам FK таблицы (доп. инфо).
Часто именно связанные таблицы в БД подсказывают структуру JSON:
▫️ один-к-одному → добавить вложенный объект {}
▫️ один-ко-многим → добавить массив объектов []
👉 Названия полей в БД помогают сделать названия в JSON, но не обязательно совпадают.
👉 Не все поля из БД попадают в JSON.
👉 А иногда наоборот — в JSON нужны поля, которых ещё нет в БД. Это повод доработать модель данных.
👉 А ещё бывают ситуации с полями для JSON вычисляемыми на лету. Например, в БД есть дата рождения, а на её основании надо рассчитать возраст и вернуть в JSON отдельным полем.
2️⃣ Клиент API — интерфейс (UI) или другая система
👉 Подсказывает, какие параметры надо включить в JSON.
👉 Именно клиент — главный источник требований к JSON. Что ему нужно — то и проектируем.
▫️ Если вы работаете над API для приложения с UI — смотрите на макет и проектируйте JSON от потребностей UI.
▫️ Если вы работаете над API для интеграции с вами партнера — смотрите требования от партнера и его UI, если есть.
👉 Клиенту обычно нужны и бизнес-данные, и технические параметры (id, статусы, ссылки)
👉 Форматы данных в JSON могут отличаться от того, как они представлены на UI (пример: дата и время)
👉 Картинки в JSON приходят в виде ссылок
👉 Не все поля JSON отображаются на UI. Главное, чтобы клиент получил всё, что ему нужно. А если JSON больше — это ок.
📌 Итого:
JSON проектируется не от БД и не от UI, а между ними.
Мы соединяем:
+ то, что можем взять из БД
+ с тем, что нужно отдать клиенту
= и формируем структуру, понятную для разработчиков и полезную для клиента API.
📄 В гайде к посту — пример JSON-ответа для метода:
Получение данных о записи питомца на приём
GET /appointments/{appointmentId}
Разберите его по частям:
1. какие поля есть в JSON и как они связаны с UI?
2. что есть в JSON по сравнению с БД, а чего нет?
Полная БД VetCareGA: ссылка
🟢🔖 Подход работает:
+ для любого метода, не только GET,
+ для JSON-ответа и для тела запроса
#RestApiGA
Telegram | VK | Max