Breaking
changes

§1Что значит «сломать клиента»

Определение звучит одинаково у всех, и оно намеренно широкое.

Ключевое слово — potentially. Речь не о том, сломалось ли что-то у конкретного клиента, а о том, могло ли сломаться. Поэтому бесспорных случаев немного, и начинать стоит с них.

Между этими двумя списками есть спорная область — её и разберём.

§2Спорный случай: новое поле в ответе

В ответ добавлено поле priority, о котором старые клиенты не знают. Что произойдёт с ними, зависит от того, как они разбирают ответ.

{ "id": "a8d0…", "title": "Не работает VPN", "status": "open" }

{ "id": "a8d0…", "title": "Не работает VPN", "status": "open", "priority": "high" }

Обе ситуации встречаются на практике, поэтому крупные компании пришли к разным выводам и записали их в своих правилах.

§3Два ответа: GitHub и Azure

GitHub относит добавление поля в ответ к совместимым изменениям и перечисляет его в списке того, что выпускается без новой редакции API.

§4Почему оба правы

Различие объясняется тем, кто выступает клиентом этих API.

Отсюда следует, что совместимость определяет команда, а не само изменение. Правильное решение то, которое записано и одинаково применяется. Незаписанное решение хуже любого из двух вариантов, потому что каждый участник считает по-своему.

§5Политика учебного проекта

В проекте выбран подход GitHub, и выбор записан в docs/VERSIONING.md вместе с обязанностью клиента.

В этом проекте принято правило GitHub, поэтому клиенты MUST игнорировать
неизвестные поля ответа.

Несовместимыми считаются и допускаются только в новой мажорной версии:
- удаление или переименование endpoint;
- удаление или переименование поля ответа;
- изменение типа поля;
- добавление обязательного параметра или обязательного поля запроса;
- удаление значения из enum;
- ужесточение требований аутентификации или лимитов.

Список короткий и закрытый. Спор «ломает или нет» сводится к вопросу «есть ли это в списке», а если случая в списке нет, список дополняют отдельным изменением, а не решают на ходу.

§6Проверка машиной: oasdiff

Проверять этот список вручную при каждом изменении ненадёжно. Для сравнения двух описаний OpenAPI есть инструмент oasdiff: он находит несовместимые изменения и перечисляет их.

Разберём на конкретном изменении. В схеме обращения поле title переименовали в subject — название показалось точнее. Заодно подняли версию контракта с 1.1.0 до 1.2.0: автор счёл изменение совместимым, ведь поле никуда не делось, а только назвалось иначе.

   Ticket:
     required:
       - id
-      - title
+      - subject
     properties:
       id: { type: string, format: uuid }
-      title: { type: string, maxLength: 120 }
+      subject: { type: string, maxLength: 120 }

   info:
-    version: 1.1.0
+    version: 1.2.0

Теперь сравним новое описание с прежним:

docker run --rm -v $(pwd):/specs tufin/oasdiff breaking \
  /specs/base.yaml /specs/revision.yaml

4 changes: 4 error, 0 warning, 0 info

error [response-required-property-removed] at /specs/revision.yaml
  in API GET /api/v1/tickets
    removed the required property `items/items/title` from the response with the `200` status

error [response-required-property-removed] at /specs/revision.yaml
  in API POST /api/v1/tickets
    removed the required property `title` from the response with the `201` status

error [response-required-property-removed] at /specs/revision.yaml
  in API GET /api/v1/tickets/{ticket_id}
    removed the required property `title` from the response with the `200` status

error [response-required-property-removed] at /specs/revision.yaml
  in API PATCH /api/v1/tickets/{ticket_id}
    removed the required property `title` from the response with the `200` status

Разберём вывод по частям.

Вывод по этому изменению: либо вернуть прежнее имя поля, либо выпускать новую мажорную версию, либо — если имя действительно неудачное — добавить subject рядом со старым title, объявить title устаревшим и удалить его позже, как описано в главе 5.3.

Ту же проверку выполняет сборка при каждом pull request — задача breaking-changes сравнивает описание из ветки с описанием в main и не даёт объединить изменение, если нашлись ошибки. Подробно про сборку — глава 6.4.

§7Чего oasdiff не видит

Инструмент сравнивает описания, а не поведение. Всё, чего нет в описании, для него не существует.

Отсюда два практических следствия. Первое: чем подробнее описание, тем больше находит машина — объявленное перечисление ловит ошибку, необъявленное не ловит ничего. Второе: проверка машиной не отменяет ревью человеком, и именно поэтому изменение контракта в проекте требует и зелёной сборки, и одобрения владельца.