🦁

マイナーバージョンアップで API レスポンスの形が静かに変わっていた話

に公開
API
バージョン管理
diff
テスト自動化
回帰テスト
tech

はじめに

バックエンドエンジニアとして、少し気になっていることがあります。

API レスポンスの形が静かに変わったとき、それを誰が検知するべきなのか、という話です。

最近、UI 駆動の API 回帰チェックを小さく試していました。同じ UI シナリオを 2 つのバックエンドバージョンに対して実行し、その間に発生した API 通信を記録して、JSON レスポンスの差分を見る、というものです。

厳密な意味でのコントラクトテストではありません。既存のユーザーフローを使って、「実際に画面が叩いている API の形が、アップグレード前後で変わっていないか」を見るだけです。

起きたこと

Medusa を v2.13.6 から v2.14.0 に上げるケースで試しました。パッチからマイナーへの、よくあるアップグレードです。

UI テストはグリーン。インテグレーションテストもグリーン。CHANGELOG にも、特に気になる記述はありませんでした。

ただ、API 通信の差分を見ると、GET /admin/orders/{id}/preview のレスポンスに email フィールドが増えていました。v2.13.6 にはなく、v2.14.0 にはあるフィールドです。

該当箇所をソースまで追うと、previewOrderChange の select 配列に 1 つだけ項目が増えていました。

v2.13.6 (packages/modules/order/src/services/order-module-service.ts):

const order = await this.retrieveOrder(orderId, {
  select: ["id", "version", "items.detail", "summary", "total"],
  relations: ["transactions", "credit_lines"],
}, sharedContext)

v2.14.0（同じファイル、1 行追加）:

const order = await this.retrieveOrder(orderId, {
  select: ["id", "version", "items.detail", "summary", "total", "email"],  // ← email 追加
  relations: ["transactions", "credit_lines"],
}, sharedContext)

email 自体は Order エンティティに以前から存在していました。変わったのは、「preview エンドポイントがそのフィールドを返すようになった」という点です。

1 トークンの追加です。リリースノートにも、CHANGELOG にも、マイグレーションガイドにも見当たりませんでした。

既存のテストでは気づけなかった

この変更は、今回のスタックでは既存テストに引っかかりませんでした。

  • UI はその画面で email を表示していない
  • API は一部のユニットテストではモックされている
  • インテグレーションテストは「期待するフィールドがあること」は見ているが、「余計なフィールドがないこと」は見ていない

もちろん、厳密なコントラクトテストやスキーマ検証を全エンドポイントに対して運用していれば検知できたはずです。ただ、現実にそこまで維持できているチームがどれくらいあるのかは分かりません。

聞きたいこと

この話で確認したいのは、手法そのものよりも運用上の感覚です。

  1. API レスポンスの形が静かに変わることは、実務でどのくらい問題になりますか？
    たとえば、フィールドが増える、型が変わる、nullable が変わる、デフォルト値が変わる、といったケースです。

  2. この種の API 契約ドリフトは、誰が検知する責任を持つべきだと思いますか？
    QA / テスト自動化、バックエンド開発者、コントラクトテストの管理者、プラットフォームチーム、下流の利用者、あるいは壊れてから気づくもの、など。

個人的には、「テストがグリーン」と「API 契約が変わっていない」は別の命題だと感じています。ただ、それをどこまで自動で見に行くべきなのか、そして誰の仕事として扱うべきなのかは、まだうまく整理できていません。

似たような変更で困った経験や、逆に「そこは普通はこう管理している」という話があれば聞いてみたいです。

タグ

API テスト自動化 回帰テスト JSON Diff バージョン管理

Discussion