Версионирование и deprecation
Принцип
Текущий major — v1 (префикс путей /v1/...). Правило простое:
- Аддитивные изменения (новое поле в ответе, новый необязательный параметр запроса, новый эндпоинт, новое значение перечисления, если клиент по спецификации обязан игнорировать незнакомые значения) публикуются в любой момент, без анонса заранее и без смены major. Существующие поля, эндпоинты и коды состояния при этом не меняют смысл.
- Breaking-изменения (переименование или удаление поля, смена типа поля, смена смысла существующего кода ошибки, удаление эндпоинта, сужение уже принятого набора значений) выходят только в новом major (
/v2/...) — не переиспользуют текущий префикс. Минимум за 90 дней до отключения предыдущего major публикуется дата отключения.
Это уже происходит на практике: docs/PARTNER_API_V2_SPEC.md описывает следующий этап (каталог, зоны, checkout, лояльность, профиль гостя) как расширение текущего /v1 контракта, а не новый major — потому что все новые эндпоинты и поля аддитивны. Смена major понадобится только если что-то из уже живого v1-контракта придётся сломать.
Что считается breaking
| Изменение | Аддитивное | Breaking |
|---|---|---|
| Новое поле в JSON-ответе | ✅ | |
| Новый необязательный параметр запроса | ✅ | |
| Новый эндпоинт | ✅ | |
Новое значение enum в поле, где клиент обязан игнорировать неизвестные значения (например state, deliveryStatus) | ✅ | |
| Удаление или переименование существующего поля | ✅ | |
| Смена типа существующего поля (например строка → число) | ✅ | |
Смена HTTP-статуса или кода error для уже существующего случая | ✅ | |
| Сужение уже принятого набора значений enum | ✅ | |
| Удаление эндпоинта | ✅ |
Практическое следствие для вашей интеграции: разбирайте JSON-ответы терпимо к новым полям (не используйте строгую схему с запретом лишних полей на чтении ответов AploDelivery — строгий разбор нужен только на запись собственных запросов) и обрабатывайте enum-поля через default/unknown-ветку, а не через закрытый switch.
Deprecation-заголовки
Если поле или эндпоинт помечен к выводу из эксплуатации, ответ содержит заголовок Deprecation (RFC 8594) и, если известна точная дата отключения, Sunset. <уточняется>: точный формат значения Deprecation/Sunset в этом сервисе ещё не реализован в коде на дату публикации (internal/httpapi/server.go не выставляет эти заголовки) — раздел будет обновлён, когда механизм появится.
Что не входит в это правило
Исправление явного бага, из-за которого сервис нарушал собственный документированный контракт (например отдавал невалидный JSON), не считается breaking-изменением API и может быть выпущено без 90-дневного анонса — версионируется как патч в Changelog.