Примерное время чтения : 7 min · Опубликовано
Выберите задачи перед адресами
Список таких использования, как поиск продукта, чтение доступности, обновление записи или отслеживание обработки. Определите авторизованных людей и системы для каждой операции. Общедоступный API чтения и административный API имеют разные требования к доступу.
Подготовьте пример запроса и ответа для каждой существенной задачи, используя синтетические значения и поясняемые поля. Различают стабильные идентификаторы, метки, единицы и даты. Определите отсутствующие данные вместо того, чтобы заменять правдоподобные значения неизвестной информации.
Задайте представление больших идентификаторов в JSON. Для JavaScript Number binary64 целые от −9007199254740991 до 9007199254740991 входят в точный диапазон совместимости RFC 8259. 9007199254740992 представимо, но небезопасно как целое: соседний токен 9007199254740993 округляется до 9007199254740992 стандартным декодированием JSON JavaScript.
Идентификатор как строка JSON сохраняет цифры. Согласуйте тип между производителем, схемой и потребителем; перевод уже округленного Number в текст не восстановит оригинал. Другие библиотеки могут сохранять больше точности: проверьте поддержанные клиенты. Верный синтаксис JSON не доказывает сохранность значений; тип не должен меняться молча.
Прокрутите таблицу по горизонтали, чтобы прочитать все столбцы. При работе с клавиатурой переведите фокус на таблицу и используйте клавиши со стрелками.
| Учебный токен JSON | Показанное значение JavaScript | Толкование |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Безопасное целое в примере |
| 9007199254740992 | 9007199254740992 | Точно, но вне безопасного диапазона |
| 9007199254740993 | 9007199254740992 | Округление: исходная последняя цифра потеряна |
| "9007199254740993" | "9007199254740993" | Точная строка; текстовый тип согласован |
Опишите явный контракт
OpenAPI предоставляет независимый от языка формат описания для API HTTP, охватывающих операции, параметры, ответы и модели. Выберите версию, поддерживаемую вашими инструментами, и сохраните документ вместе с проектом; Новейшая версия не подходит автоматически для каждой цепочки инструментов.
Ограничения использования документов, разбивка на страницы, фильтры, заказы, ошибки и пустые ответы. Не относитесь к CORS как к доказательству авторизации. Ознакомьтесь с управлением операциями и доступом на уровне объектов с технической командой.
Для вымышленного API обработки обращений отдельно опишите четыре ответа ниже. В этом контракте 201 возвращает созданный ресурс с заголовком Location, а 202 — ссылочный номер отслеживания, поскольку работа ещё не завершена. Не превращайте любой ответ 2xx в «операция завершена». Клиент должен прочитать статус, заголовки и модель, предусмотренную для операции.
Ответ 204 не содержит тела для разбора как JSON. В примере синтаксически корректная инструкция, нарушающая бизнес-правило, получает 422 со структурированной проблемой в application/problem+json. Если передаётся поле status, его генератор обязан согласовать значение с реальным HTTP-статусом; переведённый текст detail не должен становиться ключом программного решения. Документируйте стабильные идентификаторы проблем и ожидаемое исправление.
Прокрутите таблицу по горизонтали, чтобы прочитать все столбцы. При работе с клавиатурой переведите фокус на таблицу и используйте клавиши со стрелками.
| Предусмотренный ответ | Установленный факт | Проверка потребителя |
|---|---|---|
| 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.
Не дать одному редактору затереть изменения другого
- Два чтения r7
- Первая запись: r8
- Устаревшая запись: 412
- Сравнить перед продолжением
Вымышленный сценарий: два редактора открывают 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", сравнить и решить | Сохранить черновик и проверить права до новой записи. |
- IETF · RFC 9110 § 13.1.1
IETF : Условная запись и предусловия
- IETF · RFC 6585 § 3
428 · Precondition Required
Тестовые границы и разрешения
Попробуйте существующий объект, отсутствующий объект, недопустимый параметр и список длиннее одной страницы. Проверьте следующую страницу на наличие потерь или повторов в выбранной модели обновления. Ограничения состояния, которые API не может гарантировать.
Используйте тестовые учетные записи с разными разрешениями. Попытка считывания и изменения за пределами разрешенной области применения синтетических данных. Записывайте ожидаемые статусы и полезные сообщения без раскрытия внутренних трасс или секретов конфигурации.
Смена плана и поддержка
Отличите добавленное поле от удаленного поля или измененное значение. Определите потребителей до несовместимого изменения. Объясните переходный период и то, как обнаружить интеграции, все еще используя предыдущий контракт.
Предоставьте исполняемый пример для тестовой среды, тестовой матрицы и технического контакта. Связать наблюдаемые ошибки с задокументированными примерами после выпуска. Документация, ограниченная идеальным корпусом, оставляет интеграторы без руководства по отказам и прерываниям.
Первичная документация: Инициатива OpenAPI : спецификация.
Справочные документы
- Инициатива OpenAPI : спецификация · Источник просмотрен
- IETF : RFC 8259: JSON numbers · Источник просмотрен
- TC39 : Number.isSafeInteger · Источник просмотрен
Содержание обновлено
Документированные ориентиры по теме
| Источник | Значение или синтаксис | Область применения |
|---|---|---|
| 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" → 412 | If-Match сравнивает сильный валидатор до записи. В показанном контракте устаревшая версия получает 412; черновик сохраняется для сравнения изменений. |
| HTTP · 428 | 428 · Precondition Required | 428 позволяет серверу потребовать условный запрос. Его применение описывают в контракте; сам статус не обеспечивает блокировку. |
Даты обозначают обращение к источникам. Эти сведения не являются аудитом сайта или общим заявлением о соответствии.
