Проверка JSON

Как проверять JSON-ответ API, а не только код HTTP 200

Практическое руководство по путям к полям, операциям сравнения, типам значений, массивам и диагностике ситуаций, когда endpoint отвечает успешно, но возвращает неправильные данные.

Создать аккаунт Открыть материалы

Настройка правил проверки JSON-ответа API в UpWatch

Краткий ответ

JSON-проверка добавляется внутрь обычного HTTP-монитора. Сначала UpWatch выполняет HTTP-запрос, затем разбирает тело ответа как JSON и проверяет указанные правила.

Правило состоит из пути, операции и ожидаемого значения. Например, путь $.status, операция «равно», ожидаемое значение ok проверяют, что поле status содержит строку ok.

Если хотя бы одно включённое правило не проходит, запуск становится неуспешным. В истории можно отличить неправильную настройку правила от корректного правила, которому не соответствует ответ API.

Какие сбои не видны по одному HTTP-статусу

HTTP 200 подтверждает успешную обработку запроса на транспортном уровне, но не гарантирует правильность данных и бизнес-состояния.

API возвращает признак ошибки внутри JSON

Endpoint отвечает 200, но поле success равно false, status содержит error или внутри объекта возвращается описание сбоя.

Исчезло обязательное поле

После релиза или изменения контракта поле может быть переименовано, перемещено или полностью удалено.

Значение стало неправильным

Поле существует, но содержит неверный статус, версию, счётчик, режим работы или другой критичный показатель.

Вернулся пустой или неполный массив

API формально доступен, но данные не загрузились из базы, кеша или внешней системы.

Ответ перестал быть JSON

Вместо API-ответа сервер может вернуть HTML-страницу ошибки, обычный текст или пустое тело.

Изменился тип значения

Число может превратиться в строку, объект — в null, а ожидаемый массив — в сообщение об ошибке.

Как UpWatch проверяет JSON

Проверка выполняется после получения HTTP-ответа и проходит несколько последовательных этапов.

Этап 1

Получение тела ответа

HTTP-монитор отправляет запрос с настроенным методом, заголовками, телом и таймаутом.

Поддерживаются методы GET, HEAD и POST.
JSON-проверки являются частью HTTP-монитора.
Для JSON нужен ответ с телом, поэтому HEAD для такого сценария обычно не подходит.
Максимальный читаемый размер тела задаётся в настройках.

Этап 2

Разбор ответа как JSON

Система пытается разобрать полученное тело как корректный JSON-документ.

Пустое тело считается ошибкой JSON-ответа.
Невалидный JSON считается ошибкой ответа.
HTML или обычный текст не пройдут разбор как JSON.
Ошибка разбора отображается отдельно от несовпадения значения.

Этап 3

Поиск значения по пути

Для каждого правила система находит поле или элемент массива по указанному пути.

Путь должен начинаться с символа $.
Вложенные поля разделяются точками.
Индекс массива указывается в квадратных скобках.
Пример: $.data.items[0].id.

Этап 4

Сравнение с ожидаемым значением

Найденное значение проверяется выбранной операцией.

Для «существует» ожидаемое значение не требуется.
Для остальных операций ожидаемое значение обязательно.
Числовые операции применимы только к числам.
Тип ожидаемого значения влияет на результат сравнения.

Этап 5

Сохранение результата

Если правило не прошло, детали сохраняются вместе с запуском.

Показывается номер правила.
Сохраняются путь и операция.
Для несовпадения отображаются ожидаемое и фактическое значения.
Ошибки настройки отделяются от ошибок ответа сервиса.

Примеры JSON-правил

Примеры соответствуют фактически поддерживаемому синтаксису и операциям.

Проверка статуса сервиса

Ответ:
{
  "status": "ok"
}

Путь: $.status
Операция: равно
Ожидаемое значение: ok

Правило пройдёт, только если поле status существует и содержит строку ok.

Проверка логического значения

Ответ:
{
  "healthy": true
}

Путь: $.healthy
Операция: равно
Ожидаемое значение: true

Значение true без кавычек распознаётся как логическое. Строка "true" была бы другим типом.

Проверка вложенного поля

Ответ:
{
  "data": {
    "version": 12
  }
}

Путь: $.data.version
Операция: больше или равно
Ожидаемое значение: 12

Числовая операция сработает только тогда, когда фактическое и ожидаемое значения являются числами.

Проверка элемента массива

Ответ:
{
  "items": [
    {
      "id": 145
    }
  ]
}

Путь: $.items[0].id
Операция: равно
Ожидаемое значение: 145

Поддерживается обращение к элементу массива по конкретному индексу.

Проверка подстроки

Ответ:
{
  "message": "service is ready"
}

Путь: $.message
Операция: содержит
Ожидаемое значение: ready

Для строки операция «содержит» проверяет наличие указанной подстроки.

Проверка элемента массива

Ответ:
{
  "roles": [
    "user",
    "admin"
  ]
}

Путь: $.roles
Операция: содержит
Ожидаемое значение: admin

Для массива операция «содержит» ищет элемент, полностью равный ожидаемому значению.

Проверка ключа объекта

Ответ:
{
  "features": {
    "payments": true
  }
}

Путь: $.features
Операция: содержит
Ожидаемое значение: payments

Для объекта операция «содержит» проверяет наличие ключа с указанным именем.

Проверка существования поля

Ответ:
{
  "request_id": "abc-123"
}

Путь: $.request_id
Операция: существует

Проверяется сам факт наличия поля. Его конкретное значение при этой операции не сравнивается.

Операции JSON-проверок

Выбор операции должен соответствовать типу фактического значения.

Операция	Что проверяет	Подходящие типы	Пример
существует	Поле или элемент найден по указанному пути.	Любой тип	$.data.id существует
равно	Фактическое значение полностью равно ожидаемому с учётом JSON-типа.	Строка, число, boolean, null, массив, объект	$.status равно ok
содержит	Подстроку в строке, элемент в массиве или ключ в объекте.	Строка, массив, объект	$.roles содержит admin
больше	Фактическое число больше ожидаемого.	Только число	$.queue_size больше 0
больше или равно	Фактическое число не меньше ожидаемого.	Только число	$.version больше или равно 12
меньше	Фактическое число меньше ожидаемого.	Только число	$.latency_ms меньше 500
меньше или равно	Фактическое число не больше ожидаемого.	Только число	$.errors меньше или равно 0

Как настроить JSON-проверку

Начинайте с одного устойчивого поля и добавляйте новые правила только тогда, когда они дают отдельную ценность.

Шаг 1

Выберите подходящий endpoint

Он должен стабильно возвращать JSON и отражать реальное состояние нужного компонента.

Не используйте случайную страницу сайта.
Не проверяйте endpoint с персональными данными без необходимости.
Предпочитайте безопасный healthcheck или диагностический endpoint.
Убедитесь, что URL доступен из внешней сети.

Шаг 2

Создайте HTTP-монитор

Настройте адрес, метод, заголовки, тело запроса и таймаут.

Выберите GET или POST в зависимости от API.
Добавьте авторизационный заголовок только при необходимости.
Не размещайте чувствительные данные в публичном endpoint.
Проверьте HTTP-ответ до добавления JSON-правил.

Шаг 3

Включите проверку JSON

После включения необходимо оставить хотя бы одно правило.

Укажите максимальный размер читаемого JSON.
Для большинства небольших ответов подходит значение по умолчанию.
Слишком маленький лимит может обрезать нужную часть ответа.
Не увеличивайте лимит без необходимости.

Шаг 4

Добавьте путь и операцию

Путь должен указывать ровно на проверяемое значение.

Начинайте путь с $.
Используйте точки для вложенных полей.
Используйте [0], [1] и другие индексы для массивов.
Не используйте неподдерживаемые фильтры JSONPath.

Шаг 5

Укажите ожидаемое значение

Значение автоматически распознаётся как JSON там, где это возможно.

10 распознаётся как число.
true распознаётся как логическое значение.
null распознаётся как null.
Обычный текст распознаётся как строка.
Для операции «существует» значение не требуется.

Шаг 6

Проверьте первый запуск

Откройте историю и убедитесь, что правило проверяет именно то поле, которое вы ожидали.

Проверьте успешный запуск.
Временно измените ожидаемое значение для безопасного теста ошибки.
Посмотрите expected и actual.
Верните правильную конфигурацию после теста.

Почему JSON-проверка не проходит

Ошибка правила и ошибка ответа — разные проблемы, которые нужно исправлять по-разному.

Симптом	Возможная причина	Что делать
Ответ не является валидным JSON	Endpoint вернул HTML, обычный текст, пустое тело или повреждённый JSON.	Проверьте тело ответа, HTTP-статус, Content-Type, прокси и фактический URL.
Путь должен начинаться с $	В правиле указан путь вроде data.status вместо $.data.status.	Добавьте символ $ в начало пути.
Некорректный индекс в пути	В квадратных скобках находится не целое число либо отсутствует закрывающая скобка.	Используйте формат $.items[0].id.
Поле по указанному пути не найдено	Структура ответа изменилась, допущена ошибка в имени либо выбран несуществующий индекс.	Сравните путь с фактическим JSON из текущего запуска.
Значение не равно ожидаемому	Значения различаются по содержимому или JSON-типу.	Сравните expected и actual. Проверьте, не сравнивается ли число со строкой.
Числовое сравнение не работает	Фактическое или ожидаемое значение является строкой, boolean, null или другим нечисловым типом.	Исправьте ответ API либо используйте другую операцию.
Операция «содержит» не проходит	Тип значения не является строкой, массивом или объектом либо ожидаемое значение имеет неправильный тип.	Проверьте фактический тип и правила работы операции для него.
Правила сохранены, но не применяются	JSON-проверки выключены или недоступны на текущем тарифе.	Проверьте переключатель, эффективное состояние и ограничения тарифа.

Как не создать нестабильный монитор

Плохое правило создаёт шум и ложные инциденты. Хорошее проверяет устойчивый признак реальной работоспособности.

Не проверяйте случайные данные

Идентификаторы, временные метки и динамические значения меняются при каждом запросе и редко подходят для точного равенства.

Проверяйте критичный признак

Лучше проверить одно поле readiness, чем десятки второстепенных деталей ответа.

Учитывайте тип значения

Число 10 и строка "10" — разные JSON-значения. Сравнение должно соответствовать реальному контракту.

Не привязывайтесь к первому элементу без причины

Путь $.items[0] ненадёжен, если порядок массива может меняться.

Не передавайте секреты в ответе

Healthcheck не должен возвращать токены, персональные данные и внутренние конфигурации.

Обновляйте монитор вместе с контрактом

Если API намеренно изменился, правила нужно обновить одновременно с релизом.

Что доступно в UpWatch

JSON-проверки встроены в обычный HTTP-монитор и используют общую историю запусков и инцидентов.

Несколько правил

Один HTTP-ответ можно проверять по нескольким независимым путям.

Семь операций

Поддерживаются существование, равенство, содержание и четыре числовых сравнения.

Вложенные поля и массивы

Можно обращаться к свойствам объектов и элементам по числовому индексу.

Ограничение размера тела

Настройка ограничивает объём JSON, который требуется прочитать для проверки.

Expected и actual

При несовпадении в деталях запуска отображаются ожидаемое и фактическое значения.

Отдельные типы ошибок

Невалидный JSON, ошибка настройки и несовпадение ответа различаются в истории.

Ограничения

Поддерживается упрощённый путь, а не полный стандарт JSONPath.
Нет фильтров массивов вида [?()] и поиска элемента по значению.
Нет масок, рекурсивного поиска и функций JSONPath.
Индекс массива должен быть известен заранее.
JSON-проверка не выполняет последовательность нескольких API-запросов.
Проверка не сохраняет и не передаёт значение из одного запроса в другой.
Проверка не заменяет контрактные, интеграционные и end-to-end тесты.
Доступное количество правил зависит от тарифа.

Частые вопросы

Является ли JSON-проверка отдельным монитором?

Нет. Это дополнительный слой внутри HTTP-монитора.

Что произойдёт, если одно из правил не выполнится?

Весь запуск будет считаться неуспешным и может участвовать в открытии инцидента.

Можно ли проверять массивы?

Да. Можно обратиться к элементу по конкретному индексу, например $.items[0].id, либо применить «содержит» ко всему массиву.

Можно ли найти элемент массива по его полю?

Нет. Фильтры JSONPath в текущей реализации не поддерживаются.

Чем число 10 отличается от строки "10"?

Это разные JSON-типы. Для точного равенства фактический и ожидаемый типы должны совпасть.

Что означает ошибка конфигурации?

Правило само составлено неправильно: например, путь некорректен или ожидаемое значение отсутствует.

Что означает ошибка ответа?

Правило корректно, но API вернул невалидный JSON, не найденное поле или значение, не соответствующее ожиданию.

Связанные материалы

Дополнительные руководства помогут связать настройку с API, историей запусков, инцидентами и уведомлениями.

Мониторинг API

Настройка URL, HTTP-метода, заголовков, тела запроса и таймаута.

Диагностика ошибок API

Разбор HTTP-кодов, таймаутов, неправильных ответов и ошибок контракта.

История проверок

Где смотреть результаты правил, expected, actual и причины ошибки.

Инциденты

Как последовательные неуспешные проверки объединяются в период проблемы.

Проверяйте смысл ответа API

Добавьте правила для критичных полей JSON и обнаруживайте ошибки, которые не видны по одному HTTP-коду.

Создать аккаунт Открыть справочный центр