JSON для API от А до Я: гайд для системного аналитика
Аналитик не пишет код, но именно он описывает контракт API — тот документ, по которому фронтенд и бэкенд договариваются, кто что кому передаёт. Если контракт кривой, команда неделями уточняет детали в чате. Если чёткий — разработка идёт молча.
Разберём JSON API по частям: из чего он состоит, как читается и как описывать его в ТЗ, чтобы не переспрашивали.
Что такое JSON
JSON — это формат обмена данными. Не язык программирования, а способ записать структуру: какие есть поля и какие у них значения. Читается как анкета — слева название поля, справа значение.
{ "order_id": "a3f9", "status": "delivered", "paid": true, "total": 12050 }
Здесь четыре поля. У заказа есть идентификатор, статус, флаг оплаты и сумма. Всё, что нужно понять на старте: фигурные скобки — это один объект (одна карточка), а внутри пары «поле: значение».
Типы данных
В JSON шесть типов, и путать их нельзя — от этого зависит, как данные обработает система:
- Строка — "Москва", всегда в двойных кавычках
- Число — 12050, без кавычек и разделителей тысяч
- Булево — true / false, флаг, а не строка "true"
- Массив — [1, 2, 3], список значений
- Объект — { "city": "Москва" }, вложенная структура
- null — значение отсутствует
Частая ошибка новичка в ТЗ — попросить число или флаг «строкой». "qty": "2" и "qty": 2 для разработки это разные вещи: первое придётся приводить к числу, и однажды это сломается.
Как устроен запрос и ответ
API — это разговор двух систем. Одна отправляет запрос, вторая возвращает ответ.
Запрос:
GET /api/v1/orders/a3f9
GET — метод (получить данные). Дальше путь к ресурсу. Основные методы, которые аналитику нужно знать:
- GET — получить данные (ничего не меняет)
- POST — создать новое
- PUT / PATCH — обновить существующее
- DELETE — удалить
Ответ:
200 OK { "order_id": "a3f9", "status": "delivered", "created_at": "2026-07-20T14:30:00Z" }
200 — код ответа, о нём ниже. Дальше тело ответа в JSON.
Даты и деньги — две главные боли
Даты. Пиши в формате ISO 8601 с таймзоной: 2026-07-20T14:30:00Z. Формат 20.07.2026 — путаница между русской и американской записью и головная боль при сортировке. Таймзона обязательна, иначе непонятно, чьё это время.
Деньги. Не храни во float — из-за округления 0.1 + 0.2 даст 0.30000000000000004. Храни сумму в минорных единицах целым числом (12050 копеек = 120,50 ₽) и выноси валюту отдельным полем:
{ "amount": 12050, "currency": "RUB" }
Списки и пагинация
Коллекцию нельзя отдавать целиком — если заказов 400 тысяч, ответ повесит и сервер, и клиент. Список приходит порциями:
{ "items": [ ... ], "total": 400000, "page": 1, "per_page": 50 }
items — текущая страница, total — сколько всего, page и per_page — навигация. В ТЗ на любой список сразу закладывай пагинацию.
Коды ответов
Код в ответе говорит, что произошло, ещё до чтения тела. Аналитику хватит трёх групп:
- 2xx — успех. 200 OK, 201 Created (создано).
- 4xx — ошибка на стороне клиента. 400 — плохой запрос, 401 — не авторизован, 403 — нет прав, 404 — не найдено.
- 5xx — сбой на сервере.
Главное правило: не отдавай ошибку с кодом 200. Ответ «200 OK + {"error": "не найдено"}» ломает всю обработку — клиент считает, что всё хорошо. Не найдено — значит 404.
Формат ошибки
Ошибка тоже часть контракта, и её формат должен быть единым на всех эндпоинтах. Минимум — машиночитаемый код и человекочитаемое сообщение:
400 Bad Request { "code": "INVALID_DATE", "message": "Неверный формат даты" }
code разработчик разбирает программно, message показывает пользователю. Для ошибок валидации добавляй, какое именно поле не прошло.
Версионирование
API живёт и меняется. Чтобы обновление не сломало тех, кто уже пользуется старой версией, версию выносят в путь (/api/v1/) или заголовок. Ломающие изменения — это новая версия (v2), а не правка существующей.
Как это описывать в ТЗ
Собираем всё вместе. Хорошее описание метода в ТЗ содержит:
- Метод и путь — GET /api/v1/orders
- Параметры запроса — какие обязательны, какие нет, их типы
- Пример ответа при успехе — реальный JSON, а не «структура заказа»
- Пример ответа при ошибке — код и тело
- Коды ответов — что и когда возвращается
- Описание каждого поля — тип, обязательность, единицы измерения, для enum — список допустимых значений
Один реальный пример запроса и ответа экономит десяток уточняющих вопросов от разработки.
Коротко
JSON — это анкета из полей и значений. Задача аналитика — описать контракт так, чтобы у разработчика не осталось вопросов: типы полей, формат дат и денег, пагинация списков, коды ответов, единый формат ошибок, версия и пример. Пройдёшь по этому списку до разработки — на ревью не прилетит половина правок.
Разбираю системный анализ по шагам, без воды и с нуля — в Telegram: @solo_teach. А в закрепе канала лежит чек-лист приёмки JSON API на 15 пунктов — забирай.
