Как актуальные каталоги возможностей уменьшают расхождения документации с API: отдельно проверяем заявленные характеристики, выполнение и доставку

При написании документации API самые опасные ошибки часто выглядят вполне разумно. Идентификатор google_maps для платформы с отзывами может показаться более запоминающимся, чем google_maps_reviews; добавление параметра since в каждый эндпоинт отзывов соответствует интуитивному представлению об инкрементальной загрузке. Но правдоподобность не означает фактической поддержки, и читатели, скопировавшие такие примеры, застревают на первом же шаге.

Во время этой проверки контента в EveryInfra мы сверили упомянутые в статье возможности с публичным каталогом и параллельно выполнили проверку реализации в режиме только для чтения. Этот процесс ещё раз показал, что актуальные каталоги полезны, но не являются универсальным доказательством корректности. Сопровождение документации должно отвечать на вопросы, что заявляет сервис, что произошло при обработке запроса и что получил бизнес, вместо того чтобы полагаться на единственный «зелёный» статус.

Ценность каталога на примере трёх конкретных расхождений

Первое расхождение касается идентификатора платформы. При запросе google_maps к публичному каталогу 2026-09-04 в 20:46 (по пекинскому времени) был получен ответ HTTP 400 с кодом unknown_capability и подсказкой google_maps_reviews. Каталог выявляет неверное название, но редактору всё равно нужно убедиться, что целью действительно являются отзывы о местах; автоматически выбирать любой похожий вариант нельзя.

Второе расхождение касается параметров отзывов Amazon. Публичная запись в каталоге за тот же день содержит только url и domain, без конкретных значений default_limit и max_limit. Описания параметров в локальной реализации подробнее, но на них нельзя ссылаться как на развёрнутые возможности. В тексте нужно использовать только проверяемые границы; если верхний предел не объявлен, его можно зафиксировать только как неизвестный, а не как неограниченный.

Третье расхождение касается обнаружения через MCP. При проверке в 20:43 были обнаружены шесть инструментов, однако в ответ на уведомление о завершении инициализации пришло неожиданное тело ответа. Совпадение названий и количества инструментов не доказывает полного соответствия протоколу и тем более того, что каждый клиент прошёл аутентификацию и выполнил реальный вызов. Для этого расхождения нужен отдельный пункт приёмки, его нельзя прятать за нормальным статусом каталога.

Повторная проверка от 2026-09-08 тем же путём сохраняет эту историю и подтверждает, что публичный каталог вырос до восьми инструментов, а на уведомление о завершении инициализации возвращается HTTP 202 с телом ответа размером 0 байт. Прежнее расхождение не повторилось, но бизнес-инструменты не выполнялись, поэтому аутентификация хоста, фактические результаты и долгосрочная совместимость по-прежнему не отмечены как проверенные.

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

Разделение структуры, выполнения и доставки на три уровня

• Структурные доказательства: текущий каталог задаёт действия, обязательные параметры, допустимые значения и поля ответа, используемые для построения запросов и стратегий разбора.
• Доказательства выполнения: конкретный GET-запрос, HTTP-запрос или обнаружение через протокол успешно завершается, а входные данные, тип ответа, статус и время наблюдения фиксируются.
• Доказательства доставки: при выполнении разрешённой бизнес-задачи получены данные в документированном формате, а пустые результаты, частичное выполнение, сбои и списания проверены; для этого требуется отдельная бизнес-приёмка.

Наличие owner_response в каталоге не доказывает, что на каждый отзыв есть ответ продавца. Получение 200 не доказывает, что вся пагинация пройдена. Один успешный бизнес-образец не доказывает работоспособность каждого элемента каталога. В статьях рядом с утверждениями нужно указывать соответствующий уровень доказательств, а не подкреплять сильное обещание более слабой проверкой.

Одно машиночитаемое описание API вместо дублирования пояснений

Одна и та же возможность может встречаться в HTTP-документации, каталогах возможностей, описаниях полей, схемах MCP и примерах в статьях. При сопровождении идентификаторы, входные данные и определения полей можно брать из одного переиспользуемого описания API, а разным выходным материалам оставить свои задачи: каталог помогает находить возможности, страницы полей объясняют семантику, примеры показывают задачи читателя, а тесты проверяют поведение в рантайме.

Генерация справки по возможностям и проверка параметров в текущем коде EveryInfra поддерживают такое переиспользование; однако наличие общих функций не доказывает, что все онлайн-страницы и развёрнутые экземпляры синхронизированы. Текст, написанный людьми, не получает автоматически правильных сценариев использования, границ авторизации и объяснений сбоев только потому, что опирается на тот же каталог.

OpenAPI описывает HTTP-интерфейсы и их структуры и составляет часть этого подхода к сопровождению. Семантику действий, отсутствующие поля, охват примеров и ограничения использования всё равно нужно явно документировать в реальном бизнес-контексте. Автоматическая генерация уменьшает ошибки в полях при копировании, но не заменяет редакторскую оценку того, не расширяет ли формулировка заявленные возможности.

При сравнении структур нужно также различать properties, обязательные поля и значения null. В официальном руководстве по JSON Schema прямо указано, что поля, перечисленные в properties, по умолчанию не являются обязательными. Если сравнивать только наборы названий полей, можно пропустить изменение, при котором необязательное поле становится обязательным; и наоборот, допустимость отсутствия поля не означает, что разрешено явное значение null.

Запрашивайте только ту справку, которая нужна для конкретного руководства

При интеграции сначала определите платформу и объект, а затем уточните действие. На следующих шагах публичный каталог читается без получения отзывов и без API-ключа. Поскольку jq выводит null для выбранных свойств, которых нет в ответе, важно различать исходный ответ без поля и ответ, в котором явно указано значение null; ни то ни другое нельзя произвольно трактовать как ноль.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=amazon' \
  | jq -e '.capabilities[] | select(.action == "reviews") | {
      platform, action, required_params, optional_params, param_meanings,
      mode, returns_list, default_limit, max_limit, response_fields
    }'

Добавляйте к этим наблюдениям URL-адреса источников, временные метки получения и сводки фактических ответов. Если запрос или разбор завершается сбоем, не перезаписывайте старый снимок пустым каталогом. Сохраните прежнее содержимое и статус сбоя, чтобы сопровождающие понимали, что новые описания не были получены, а не считали, что сервис удалил все возможности.

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

Сравнивайте семантические различия, а не исходный текст JSON

Порядок ключей объекта, порядок отображения списков и правки поясняющего текста могут создавать впечатление, что файл сильно изменился, хотя способ вызова остался прежним. И наоборот, достаточно изменить одно значение returns_list с true на false, чтобы сломать парсер. Сначала выберите поля для проверки, затем классифицируйте различия.

function contractDiff(before, after) {
  if (before.platform !== after.platform || before.action !== after.action) {
    throw new Error("compare the same capability");
  }
  const normalize = row => {
    const names = key => {
      const values = row[key];
      if (!Array.isArray(values)
          || values.some(v => typeof v !== "string" || !v.trim())
          || new Set(values).size !== values.length) {
        throw new Error("explicit unique field list required");
      }
      return [...values].sort();
    };
    if (typeof row.mode !== "string" || !row.mode
        || typeof row.returns_list !== "boolean") {
      throw new Error("explicit mode and result shape required");
    }
    return {
      required_params: names("required_params"),
      response_fields: names("response_fields"),
      mode: row.mode, returns_list: row.returns_list
    };
  };
  const left = normalize(before), right = normalize(after);
  return Object.keys(left).filter(key =>
    JSON.stringify(left[key]) !== JSON.stringify(right[key]));
}

const baseline = {
  platform: "synthetic", action: "comments",
  required_params: ["url"], response_fields: ["id", "text"],
  mode: "sync", returns_list: true
};
console.log(contractDiff(baseline, {
  ...baseline, response_fields: ["text", "id"]
}));
console.log(contractDiff(baseline, {
  ...baseline, required_params: ["url", "region"]
}));

Два итоговых результата соответствуют отсутствию различий и изменению required_params. Этот механизм сравнивает только четыре явно заданные структуры и не выполняет полную проверку совместимости; необязательные параметры, перечисления, типы полей, количественные ограничения, доступность и условия оплаты нужно проверять отдельно. Отсутствие любой из структур приводит к ошибке: оно не трактуется молча как пустой список.

Особого внимания требуют добавление обязательных входных параметров, удаление используемых полей, сужение перечислений или количественных диапазонов и изменение режимов выполнения. Даже при добавлении полей ответа нужно проверить, не отклоняют ли нижестоящие компоненты неизвестные поля. Детекторы лишь отмечают изменения; сопровождающие должны проверить их влияние на реальных потребителей, а не автоматически делать выводы о совместимости.

Кэш хранит наблюдения, а не вечные гарантии

Ключи кэша должны как минимум различаться для разных эндпоинтов сервиса, платформ и действий; вместе с данными нужно хранить время получения и версию протокола или API. Если несколько окружений используют общие ключи кэша, тестовые описания могут попасть в продакшен. Периодичность проверки доступности, параметров и источников статей тоже может различаться, поэтому единый срок хранения не позволяет учесть все риски.

Например, если редактор назначает повторную проверку через день, это отражает рабочий процесс команды, а не серверную гарантию неизменности каталога. Обнаружение неизвестных параметров, изменений структуры ответа или обновлений развёрнутой версии должно запускать точечное обновление, а не ожидание заданного срока. Устаревшее содержимое можно просматривать, но операции с серьёзными последствиями не должны по-прежнему опираться на неподтверждённые прежние описания.

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

Если сервис отдаёт соответствующие заголовки ответа, механизмы условных запросов и повторной валидации из RFC 9111 помогают определить, можно ли повторно использовать кэш. В этом тексте не проверяется, поддерживает ли каталог ETag или 304; без явной поддержки со стороны сервиса локальные сводки нельзя считать серверными валидаторами, а периодичность проверок нельзя называть обязательствами сервера по кэшированию.

Рассматривайте примеры из статей как API-клиента

Для проверки примеров нужно извлекать код непосредственно из самих статей, а не писать отдельные тестовые запросы, которые лишь кажутся идентичными. Бесплатные команды каталога можно проверять напрямую; для бизнес-запросов POST без авторизованных примеров сначала проверяйте синтаксис, формирование запроса и ветки обработки ответа в офлайн-режиме, явно отмечая результаты сервиса как непроверенные. Не допускайте ситуации, когда тестовая копия верна, а в версии из статьи, которую копирует читатель, limit находится на неверном уровне вложенности.

Ссылки также нужно проверять на соответствие назначению. Страницы возможностей на сайте помогают продолжить интеграцию, а официальная документация подтверждает исходные определения соответствующих продуктов и протоколов; официальная ссылка на платформу не означает одобрения всех способов использования EveryInfra. В неопубликованных статьях не стоит преждевременно указывать ссылки на страницы с подробной информацией, которые могут возвращать ошибку 404.

Порядок действий после обнаружения расхождения

• Сбой чтения: сохраните статус сбоя, не подменяя его новым определением параметров; при необходимости приостановите операции, зависящие от этого описания.
• Изменение параметров или полей: перечислите затронутые параметры, поля и потребителей, затем решите, нужно ли обновить примеры, адаптировать код или сохранить блокировки.
• Разница между локальным и публичным состоянием: фиксируйте отдельно; локальные изменения не означают завершения развёртывания.
• Расхождение публичных описаний с фактическими результатами: сохраните минимальные авторизованные образцы, передайте проблему сопровождающим сервиса и ограничьте заявления в связанных статьях.
• Полное соответствие: сообщите только о том, что в рамках проверки расхождений не найдено, не публикуя статьи автоматически и не объявляя все интеграции успешными.

Начните с наиболее часто используемого бизнес-действия и создайте взаимосвязанные записи для фиксации состояния каталога, проверки примеров и приёмки результатов. Тогда обновление документации будет заключаться не просто в замене старых скриншотов новыми, а в объяснении того, какой факт изменился, кого это затрагивает и какие доказательства позволяют продолжать использование.