# API Версия источника: 4880e8b4372c96001c2e052be28b68a95d31252b Синхронизировано: 2026-11-09T11:15:07.649Z Источник: https://github.com/sergey-from-riders/vibecoding-base/tree/4880e8b4372c96001c2e052be28b68a95d31252b ## Оглавление - [HTTP-статусы](#api-http-status) - [HTTP-методы](#api-methods) - [Problem Details](#api-error-details) - [OpenAPI-контракт](#api-openapi) - [Идемпотентность API](#api-idempotency) - [Оптимистическая блокировка](#api-concurrency) - [Пагинация](#api-pagination) - [Совместимость API](#api-compatibility) - [HTTP-заголовки](#api-headers) # HTTP-статусы ## Коротко Клиент, прокси и мониторинг должны видеть результат запроса без разбора произвольного JSON. ## Плохо ```http HTTP/1.1 200 OK Content-Type: application/json {"status": 404, "message": "Не найдено"} ``` ## Хорошо ```http HTTP/1.1 404 Not Found Content-Type: application/problem+json {"type":"about:blank","title":"Не найдено","status":404} ``` ## Почему Если ошибка замаскирована успешным кодом, инфраструктура может обработать её как успех. ## Когда применять Для HTTP API. Поле status в Problem Details допустимо, но совпадает с реальным HTTP-кодом. Статус заказа — отдельное бизнес-поле. ## Как проверить - Проверьте HTTP-код отсутствующего ресурса и ошибки доступа. ## Человек Определяет бизнес-смысл ошибок и ожидаемое поведение клиента. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Проверьте HTTP-код отсутствующего ресурса и ошибки доступа. ## Источники - [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html) Уровень: Обязательно. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/http-status.md) --- # HTTP-методы ## Коротко GET и HEAD читают; изменение бизнес-состояния должно иметь соответствующий метод. ## Плохо ```http GET /orders/42/delete ``` ## Хорошо ```http DELETE /orders/42 ``` ## Почему Ссылку может заранее открыть браузер, робот или прокси. ## Когда применять POST подходит для команд и создания, PUT — полного идемпотентного замещения, PATCH — частичного изменения. Семантику повторов PATCH нужно описывать. ## Как проверить - Открытие обычной ссылки не удаляет и не оплачивает данные? ## Человек Согласует назначение операции и последствия повторного запроса. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Открытие обычной ссылки не удаляет и не оплачивает данные? ## Источники - [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html#section-9) - [rfc5789.html](https://www.rfc-editor.org/rfc/rfc5789.html) Уровень: Обязательно. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/methods.md) --- # Problem Details ## Коротко Ошибка должна помогать исправить запрос без раскрытия внутреннего устройства сервера. ## Плохо ```json {"error":"SQL exception at /private/app/main.go:42"} ``` ## Хорошо ```json {"type":"https://example.com/problems/validation", "title":"Проверьте поля", "status":422, "errors":[{"field":"email","message":"Неверный формат"}]} ``` ## Почему Стек вызовов и SQL не помогают пользователю и могут раскрыть лишние сведения. ## Когда применять Problem Details задаёт общую основу; errors и request_id — документируемые расширения, а не обязательные поля RFC. ## Как проверить - Можно ли понять ошибку? Нет ли секретов и внутренних путей? ## Человек Определяет понятные пользователю коды ошибок и допустимые детали ответа. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Можно ли понять ошибку? Нет ли секретов и внутренних путей? ## Источники - [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/error-details.md) --- # OpenAPI-контракт ## Коротко В контракте должны быть реальные методы, схемы, ошибки, доступ и примеры. ## Плохо ```text Новый endpoint работает, но в документации его нет. ``` ## Хорошо ```text Изменены обработчик, OpenAPI, пример и тест. operationId уникален и стабилен. ``` ## Почему Клиенты и агенты не должны угадывать формат запроса. ## Когда применять OpenAPI 3.2 подходит при поддержке инструментов; 3.1 остаётся допустимым осознанным выбором. Разбиение по модулям зависит от размера API. ## Как проверить - Сопоставьте реальные маршруты, операции контракта и каталог endpoints. ## Человек Утверждает публичные поля и обязательства перед клиентами. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Сопоставьте реальные маршруты, операции контракта и каталог endpoints. ## Источники - [OpenAPI Specification v3.2.0](https://spec.openapis.org/oas/v3.2.0.html) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/openapi.md) --- # Идемпотентность API ## Коротко После потери ответа повторный запрос не должен создавать вторую оплату или заказ. ## Плохо ```text Тайм-аут → новый requestId → повторное списание. ``` ## Хорошо ```text Тайм-аут → тот же Idempotency-Key. Сервер узнаёт операцию и возвращает её результат. ``` ## Почему Сетевой тайм-аут не сообщает, успел ли сервер выполнить действие. ## Когда применять Ключ связан с пользователем, операцией и содержимым. Другое содержимое под тем же ключом — конфликт. Срок хранения ключей документируется. `Idempotency-Key` — контракт конкретного API, а не обязательный заголовок RFC 9110. После истечения срока дедупликации повтор может стать новой операцией. ## Как проверить - Повторите запрос одновременно и после потери ответа. ## Человек Определяет, что считать одной операцией и как долго хранить её результат. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Повторите запрос одновременно и после потери ответа. ## Источники - [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2) - [Idempotent requests](https://docs.stripe.com/api/idempotent_requests) Уровень: Обязательно. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/idempotency.md) --- # Оптимистическая блокировка ## Коротко Проверяйте версию записи перед сохранением, если пользователь может перезаписать чужую работу. ## Плохо ```text Аня и Борис открыли v3. Аня сохранила v4. Борис молча затёр её. ``` ## Хорошо ```text Борис отправляет If-Match: "v3". Сервер отвечает 412: версия уже изменилась. ``` ## Почему Последняя запись не всегда является правильным результатом совместной работы. ## Когда применять Можно использовать ETag/If-Match либо документированный revision с 409. Не смешивайте эти договорённости неявно. ## Как проверить - Два клиента меняют одну запись: второй получает понятный конфликт? ## Человек Выбирает поведение интерфейса при конфликте изменений. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Два клиента меняют одну запись: второй получает понятный конфликт? ## Источники - [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/concurrency.md) --- # Пагинация ## Коротко Договоритесь о размере страницы, сортировке, фильтрах и продолжении списка. ## Плохо ```text GET /users → вся таблица без лимита. ``` ## Хорошо ```text GET /users?limit=50&cursor=... Ответ: items и next_cursor. ``` ## Почему Неограниченная выдача расходует память и делает время ответа непредсказуемым. ## Когда применять Cursor удобен для меняющихся списков; offset допустим для небольших стабильных выборок. Порядок должен иметь уникальный tie-breaker. ## Как проверить - Проверьте предел размера и повторяющиеся значения сортировки. ## Человек Определяет порядок списка, лимит страницы и требования к стабильности выдачи. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Проверьте предел размера и повторяющиеся значения сортировки. ## Источники - [PostgreSQL: Documentation: 18: 7.6. LIMIT and OFFSET](https://www.postgresql.org/docs/18/queries-limit.html) - [API4:2023 Unrestricted Resource Consumption - OWASP API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0xa4-unrestricted-resource-consumption/) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/pagination.md) --- # Совместимость API ## Коротко Удаление поля или изменение его смысла требует совместимости со старыми клиентами. ## Плохо ```text amount вчера означал рубли, сегодня — копейки. ``` ## Хорошо ```text Новое поле amount_minor. Старое поддерживается на время перехода. ``` ## Почему Клиент может продолжить работать без ошибки, но с неверными данными. ## Когда применять Срок перехода согласуется с потребителями. 90 дней — возможная политика проекта, а не универсальное требование протокола. ## Как проверить - Старый клиент проходит контрактные тесты новой версии? ## Человек Определяет поддерживаемых клиентов и срок перехода на новый контракт. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Старый клиент проходит контрактные тесты новой версии? ## Источники - [AIP-180: Backwards compatibility](https://google.aip.dev/180) Уровень: Обязательно. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/compatibility.md) --- # HTTP-заголовки ## Коротко Статус, формат содержимого и кеширование описываются стандартными средствами HTTP. ## Плохо ```http HTTP 200 X-App-Result: error ``` ## Хорошо ```http HTTP 503 Service Unavailable Retry-After: 30 Content-Type: application/problem+json ``` ## Почему Собственный заголовок не заменяет стандартную семантику. ## Когда применять X-Request-Id полезен для поддержки, если согласован. X-App-Result, X-App-Action и X-App-Validate не обязательны для всех API. Content-Language указывают по смыслу представления. ## Как проверить - Работает ли обычный HTTP-клиент без знания собственных заголовков? ## Человек Согласует требования клиентов, прокси и трассировки. ## Агент Реализует серверный контракт и проверяет успешный запрос, неверный ввод и повторное обращение. Контроль результата: - Работает ли обычный HTTP-клиент без знания собственных заголовков? ## Источники - [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/api/openapi-modular/rules/headers.md)