Поиск
Введите не менее двух символов без личных данных.

    БиблиотекаСтатьи и часто задаваемые вопросы Ваш проектЗапросить цитату
    ЯзыкRU ▾
    Практические руководства

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

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

    См. метод

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

    Выберите задачи перед адресами

    JavaScript округляет число 9007199254740993; строка сохраняет цифры.
    Иллюстрация · Пример JSON.parse: Number округляет токен, String сохраняет цифры. Согласуйте текстовое представление до преобразования.

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

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

    Задайте представление больших идентификаторов в JSON. Для JavaScript Number binary64 целые от −9007199254740991 до 9007199254740991 входят в точный диапазон совместимости RFC 8259. 9007199254740992 представимо, но небезопасно как целое: соседний токен 9007199254740993 округляется до 9007199254740992 стандартным декодированием JSON JavaScript.

    Идентификатор как строка JSON сохраняет цифры. Согласуйте тип между производителем, схемой и потребителем; перевод уже округленного Number в текст не восстановит оригинал. Другие библиотеки могут сохранять больше точности: проверьте поддержанные клиенты. Верный синтаксис JSON не доказывает сохранность значений; тип не должен меняться молча.

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

    Декодирование JSON JavaScript: точность и тип
    Учебный токен JSONПоказанное значение JavaScriptТолкование
    90071992547409919007199254740991Безопасное целое в примере
    90071992547409929007199254740992Точно, но вне безопасного диапазона
    90071992547409939007199254740992Округление: исходная последняя цифра потеряна
    "9007199254740993""9007199254740993"Точная строка; текстовый тип согласован

    Опишите явный контракт

    OpenAPI предоставляет независимый от языка формат описания для API HTTP, охватывающих операции, параметры, ответы и модели. Выберите версию, поддерживаемую вашими инструментами, и сохраните документ вместе с проектом; Новейшая версия не подходит автоматически для каждой цепочки инструментов.

    Ограничения использования документов, разбивка на страницы, фильтры, заказы, ошибки и пустые ответы. Не относитесь к CORS как к доказательству авторизации. Ознакомьтесь с управлением операциями и доступом на уровне объектов с технической командой.

    Для вымышленного API обработки обращений отдельно опишите четыре ответа ниже. В этом контракте 201 возвращает созданный ресурс с заголовком Location, а 202 — ссылочный номер отслеживания, поскольку работа ещё не завершена. Не превращайте любой ответ 2xx в «операция завершена». Клиент должен прочитать статус, заголовки и модель, предусмотренную для операции.

    Ответ 204 не содержит тела для разбора как JSON. В примере синтаксически корректная инструкция, нарушающая бизнес-правило, получает 422 со структурированной проблемой в application/problem+json. Если передаётся поле status, его генератор обязан согласовать значение с реальным HTTP-статусом; переведённый текст detail не должен становиться ключом программного решения. Документируйте стабильные идентификаторы проблем и ожидаемое исправление.

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

    Четыре ответа вымышленного API и последствия для клиента
    Предусмотренный ответУстановленный фактПроверка потребителя
    201 CreatedРесурс созданПроверить предусмотренный контрактом Location и созданный идентификатор
    202 AcceptedОбработка принята, но не завершенаСохранить номер отслеживания и дождаться итога
    204 No ContentДействие успешно, тела ответа нетНе разбирать пустое тело как JSON
    422 Unprocessable ContentИнструкция понята, но не обрабатывается по правилуПрочитать структурированную проблему и предложить исправление
    • RFC 9110 : HTTP Semantics

      RFC 9110, дата обращения 22 октября 2026 года: семантика статусов. Ответы и обязательные поля задают вымышленный контракт.

    • RFC 9457 : Problem Details

      RFC 9457, дата обращения 22 октября 2026 года: формат проблем и роль поля status.

    Не дать одному редактору затереть изменения другого

    1. Два чтения r7
    2. Первая запись: r8
    3. Устаревшая запись: 412
    4. Сравнить перед продолжением

    Вымышленный сценарий: два редактора открывают DEMO-17 с сильным ETag "r7". Первый сохраняет исправление; текущее представление получает "r8". Второй всё ещё работает с "r7". Условная запись позволяет выявить расхождение до замены опубликованной версии.

    Если API поддерживает такой контракт, клиент передаёт If-Match с полученным сильным валидатором. Сервер сравнивает версию до записи; в примере при изменении предусмотрен 412. W/"r7" — слабый валидатор и не подходит для сильного сравнения. If-Match: * проверяет наличие текущего представления, а не его неизменность после чтения.

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

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

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

    Два редактора, одна актуальная версия: вымышленная проверка
    ШагВерсия и запросОжидаемый результат по контракту
    Оба читаютETag: "r7"Каждый сохраняет валидатор с черновиком.
    Первое сохранениеIf-Match: "r7" → версия "r8"Первое исправление сохраняется.
    Второе устаревшее сохранениеIf-Match: "r7"; актуальная версия "r8"412; не заменять сохранённое исправление.
    Явное согласованиеПрочитать "r8", сравнить и решитьСохранить черновик и проверить права до новой записи.

    Тестовые границы и разрешения

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

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

    Смена плана и поддержка

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

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

    Первичная документация: Инициатива OpenAPI : спецификация.

    Справочные документы

    Содержание обновлено

    Документированные ориентиры по теме

    Документированные ориентиры по теме
    ИсточникЗначение или синтаксисОбласть применения
    RFC 8259 · JSON
    application/json · UTF-8Стандартный JSON не допускает комментариев и завершающей запятой; строки заключаются в двойные кавычки.
    RFC 3339 · Date-time
    2026-10-22T09:00:00+02:00Явное смещение связывает местное время с UTC; пример не обозначает запись на прием.
    HTTP · If-Match
    If-Match: "r7" → 412If-Match сравнивает сильный валидатор до записи. В показанном контракте устаревшая версия получает 412; черновик сохраняется для сравнения изменений.
    HTTP · 428
    428 · Precondition Required428 позволяет серверу потребовать условный запрос. Его применение описывают в контракте; сам статус не обеспечивает блокировку.

    Даты обозначают обращение к источникам. Эти сведения не являются аудитом сайта или общим заявлением о соответствии.

    Разделить HTTP-статус, JSON и бизнес-результат

    Выберите условный обмен и попробуйте локальное чтение. HTTP-успех, читаемый JSON и завершённая операция требуют отдельных проверок.

    Отрывки неполные и используют демонстрационные адреса. Проба создаёт Response в памяти: сервер не вызывается, сеть, кеш и бизнес-обработка не моделируются.

    200Новое полное представление
    Что это значит
    В отрывке сервер отвечает на условный GET телом JSON и валидатором demo-v2.
    Что проверить
    Сопоставьте If-None-Match, ETag и ревизию тела. Локальная проба разбирает JSON этого примера.
    На что обратить внимание
    Статус 200 не гарантирует корректный JSON или верные бизнес-данные. Успешный разбор не подтверждает схему ваших данных.
    Отрывок условного обмена
    GET /demo/catalogue
    If-None-Match: "demo-v1"
    
    HTTP/1.1 200 OK
    ETag: "demo-v2"
    Content-Type: application/json
    
    {"revision":"demo-v2"}

    202Принято, обработка ещё ожидается
    Что это значит
    202 означает принятие к обработке, а не завершение. Условное тело сообщает queued.
    Что проверить
    Сохраните DEMO-42 и проверяйте состояние по контракту API с учётом прав и ограничений повторов.
    На что обратить внимание
    Response.ok равно true. Ни это значение, ни читаемый JSON не доказывают завершение. Поля и адрес отслеживания — условные соглашения.
    Отрывок условного обмена
    POST /demo/jobs
    
    HTTP/1.1 202 Accepted
    Location: /demo/jobs/DEMO-42
    Content-Type: application/json
    
    {"job":"DEMO-42","status":"queued"}

    204Запрос выполнен, тела ответа нет
    Что это значит
    204 означает выполненный запрос без содержимого ответа. Отрывок не передаёт JSON.
    Что проверить
    Обработайте отсутствие тела по контракту. Уточните, что подтверждает получатель, прежде чем сообщать посетителю результат.
    На что обратить внимание
    Разбор пустого тела как JSON не удаётся, хотя Response.ok равно true. Webhook может подтверждать лишь получение; последующие бизнес-действия требуют сверки.
    Отрывок условного обмена
    POST /demo/events
    
    HTTP/1.1 204 No Content

    304Копия проверена, нового тела нет
    Что это значит
    304 отвечает на условный запрос: сохранённое представление можно использовать снова. Новое тело не передаётся.
    Что проверить
    Сопоставьте отправленный валидатор и доступную копию demo-v2. Толкование зависит и от этой копии.
    На что обратить внимание
    Проба создаёт отдельную Response 304, а не HTTP-кеш. При реальном fetch браузер может выдать сохранённый ответ: сетевой статус и статус в скрипте могут различаться.
    Отрывок условного обмена
    GET /demo/catalogue
    If-None-Match: "demo-v2"
    
    HTTP/1.1 304 Not Modified
    ETag: "demo-v2"

    Технические источники : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

    Матрица функциональной проверки для адаптации к проекту

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

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

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

    Часто задаваемые вопросы

    Достаточно ли сгенерированной документации для тестирования API?

    Это помогает читать контракт, но разрешения, отсутствующие данные, ошибки, списки и изменения все еще требуют тестирования. Сравните примеры с реальными ответами на тест-среду.

    CORS заменяет права доступа?

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