English · Русский
Политика версионирования и устаревания
См. также: index.md (индекс) · developer-guide.md (быстрый старт, выпуск ключа, примеры запросов) · errors.md (обработка 401/403/404/409/429/501/503) · security-model.md (localhost, модель ключей, аудит).
Применяется к каждой операции опубликованного контракта.
Версия контракта и базовый путь
Каждая операция находится под /api/v1. Основная (major) версия — часть пути.
Сам контракт несёт семантическую версию, сейчас 1.2.0. Она приходит в info.version документа OpenAPI и в поле version ответа GET /capabilities.
Версия контракта двигается по правилам ниже — на каждое изменение контракта, а не на каждый релиз продукта. Релиз, который ничего в контракте не менял, оставляет её на месте; соответствие версий продукта и контракта — в compatibility.md.
Правила semver
| Изменение | Класс | Почему |
|---|---|---|
| Исправление реализации без изменения формы | нет | Опубликованный контракт не меняется; двигается только версия продукта. |
| Исправление документации/описания/примера, без изменения формы | PATCH | Ничего, от чего зависит код клиента, не меняется. |
| Новая операция, либо новое опциональное поле в запросе/ответе | MINOR | Существующие клиенты продолжают работать без изменений; новая возможность опциональна. |
| Новый скоуп, доступный для выдачи в ключе, без изменения требуемого скоупа какой-либо существующей операции | MINOR | Чисто дополнительно к тому, что можно выпустить в ключе; не влияет на вызывающих, уже использующих API. |
| Удаление или переименование поля, либо OperationId | MAJOR | Ломает любого клиента, читающего/записывающего это поле или ссылающегося на этот id. |
| Ужесточение валидации, либо сужение/повышение требуемого тира/скоупа для существующей операции | MAJOR | Вызов, который раньше проходил с данным ключом, теперь получает 403. |
| Изменение пути, либо HTTP-глагола операции | MAJOR | Запрос клиента больше не резолвится. |
| Изменение значения по умолчанию (например, требование тира/скоупа операции меняется без запроса клиента) | MAJOR | Тихое изменение поведения при неизменной форме вызова. |
Новая MAJOR-версия увеличивает сегмент пути (/api/v1 → /api/v2); /api/v1 продолжает обслуживать существующих клиентов до тех пор, пока сам не будет выведен из эксплуатации (см. ниже). OperationId — часть публичной поверхности и никогда не переименовываются и не переиспользуются, даже между major-версиями.
Примеры
- MINOR — добавление
GET /api/v1/tasks/{id}/state(новое, использование опционально): существующие клиенты не затронуты. - MINOR — добавление опционального поля
priorityв тело запросаPUT /api/v1/tasks/{id}/config: старые клиенты, не отправляющие его, продолжают работать с существующим значением по умолчанию. - MAJOR — переименование
sessionIdвsession_idв телах ответов/api/v1/sessions/*: любой клиент, читающийsessionId, ломается. - MAJOR — повышение тира
POST /api/v1/tasksс T2 до T3, либо добавление нового обязательного скоупа к существующей операции: ранее достаточный ключ теперь получает 403.
Окно устаревания и заголовки
Окно: 90 дней с момента объявления операции устаревшей до момента её удаления (sunset), для любой заданной операции.
Манифест: устаревшая операция публикуется в опубликованном документе OpenAPI со стандартным флагом deprecated: true плюс расширением x-sunset-date (дата sunset, в формате RFC 8594 HTTP-date).
Заголовки ответа: каждый ответ устаревшей операции несёт Deprecation: true (RFC 8594; выдача на хосте подключена). Заголовок Sunset последует, когда для операции будет объявлена конкретная дата sunset.
Ноль устаревших операций сегодня
Ни одна операция в каталоге не устарела. Пока /api/v1 не выпущен, вытесненные операции удаляются сразу, минуя цикл устаревания — например, пара GET/PUT /tasks/{id}/settings/input (полностью покрыта GET/PUT /tasks/{id}/config) и GET /tasks/{id}/threads (покрыт countOfThreads в GET /tasks/{id}/state) были удалены без окна устаревания. 90-дневное окно и заголовки Deprecation/Sunset действуют с момента выпуска v1 внешним интеграторам.
Объявленные-но-не-реализованные операции (сейчас — трио подтверждений confirmations_list/confirmation_approve/confirmation_reject) — это пробел функциональности, а не устаревание: они отображаются как isAvailable: false в /capabilities и отвечают 501, а не deprecated: true в документе OpenAPI. Эти два понятия различны и не должны путаться при чтении манифеста.
Удалённые предконтрактные маршруты: /api/neurobot/*
До появления версионированной поверхности /api/v1 хост ProjectMaker обслуживал также набор алиасов /api/neurobot/*. Они никогда не были частью опубликованного контракта — их нет ни в документе OpenAPI, ни в /capabilities — и больше не существуют: /api/neurobot/* возвращает 404, а все документированные маршруты /api/v1 не затронуты.
Поскольку эти алиасы были за пределами /api/v1, их удаление не является semver-изменением опубликованного контракта. 90-дневное окно устаревания, описанное выше, регулирует операции внутри контракта и не применяется к маршрутам, которые в него никогда не входили.