REST API: Версионирование и breaking changes

REST API версионирование breaking change: 8. Версионирование

8.1. Версия в URL-пути

REST API версионирование breaking change — /api/v1/orders
/api/v2/orders

8.2. Формат: v + целое число

/api/v1/...     -- правильно
/api/v1.2/...   -- неправильно
/api/2024/...   -- неправильно

8.3. Префикс /api

Все API-эндпоинты начинаются с /api:

/api/v1/orders       -- правильно
/v1/orders           -- неправильно
/orders              -- неправильно (нет ни /api, ни версии)

8.4. Новая версия -- только при breaking change

Не создавайте v2 для добавления нового поля в ответ. Обратно-совместимые изменения допустимы в рамках текущей версии.

8.5. Что является breaking change

Breaking change -- изменение контракта, которое ломает существующих клиентов. Требует новой версии API (v1 -> v2).

Ломающие изменения (требуют новую версию):

• Удаление эндпоинта
• Удаление или переименование поля из ответа
• Удаление или переименование query-параметра или path-переменной
• Добавление нового обязательного параметра в запрос
• Изменение типа поля (string -> number, object -> array)
• Изменение формата поля (date -> date-time, изменение формата enum)
• Удаление значения из enum
• Изменение HTTP-метода эндпоинта
• Изменение URL-пути эндпоинта
• Изменение кода успешного ответа (200 -> 201)
• Изменение семантики существующего поля (поле осталось, но означает другое)
• Добавление нового обязательного заголовка
• Ужесточение валидации (было maxLength: 100, стало maxLength: 50)
• Изменение Content-Type ответа

НЕ ломающие изменения (допустимы в текущей версии):

• Добавление нового необязательного поля в ответ
• Добавление нового необязательного query-параметра
• Добавление нового значения в enum (при условии что клиенты игнорируют неизвестные значения)
• Добавление нового эндпоинта
• Добавление нового необязательного заголовка
• Ослабление валидации (было maxLength: 50, стало maxLength: 100)
• Добавление нового кода ошибки в ErrorCode enum
• Изменение текста в detail или title ошибки

Правило для клиентов: клиент должен игнорировать неизвестные поля в ответе и не падать при появлении нового значения в enum. Это позволяет серверу развивать API без breaking changes.