Версии и совместимость

Сейчас: v1 нестабильна

Версия стоит в пути с первого эндпоинта — /api/v1/… — но версии не плодятся. Это две разные вещи.

v1 в пути — это место, куда потом можно поставить v2. Стоит один сегмент. Переезд с /api/parcels на /api/v1/parcels потом стоил бы всех клиентов сразу.

При этом пока у API нет ни одного внешнего потребителя, который не может обновиться синхронно с нами, ломающие изменения выходят в v1. Так честнее, чем обещать совместимость и тихо её нарушать.

Что считается ломающим изменением

• удаление поля из ответа;
• переименование поля или эндпоинта;
• новое обязательное поле в запросе;
• сужение того, что принимается: новый максимум длины, убранное значение перечисления;
• изменение кода ответа при том же исходе.

Не ломающее: новое поле в ответе, новое необязательное поле в запросе, новое значение перечисления, новый эндпоинт. Пишите клиент так, чтобы незнакомое поле в ответе его не роняло.

Когда появится v2

Когда появится первый внешний потребитель, который не может обновиться вместе с нами. Не раньше.

До тех пор ломающие изменения объявляются заранее: старое поведение, если его вообще можно оставить, отвечает с заголовками Deprecation и Sunset, а само изменение попадает в changelog этой документации.

Что не версионируется никогда

Маршруты самого сайта. Они уезжают на прод в одном коммите с фронтендом, который их вызывает, поэтому обещание совместимости там — это обещание самим себе. Публичный контракт — это /api/v1 и MCP, и только они.