アプリを壊してしまう9つのAPI変更

𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽 アプリを壊してしまう9つのAPI変更

「何も壊していません。レスポンスを整理しただけです。」

これらの言葉は、しばしばクラッシュを引き起こします。モバイルアプリが動作しなくなり、パートナーとの連携がデタラメなデータを返すようになります。あなたは、他の誰かが依存しているデータの構造を変えてしまったのです。

危険な変更は、一見すると「整理整頓」のように見えることがよくあります。コードレビューやテストはパスしてしまうからです。しかし、問題は目に見えないコードの中で発生します。

安全に思えて、実はそうではない9つの変更を紹介します。

• フィールド名の変更 一貫性を保つために userId を user_id に変更すると、クライアントが壊れます。名前の変更は、「削除」と「追加」を同時に行う行為です。この「削除」の部分が、利用者のコードを壊します。 安全な対応策: 新しいフィールドを追加し、古いフィールドも残しておきます。その後、古いフィールドを非推奨（Deprecate）にし、かなり時間が経ってから削除します。

• フィールドを任意（Optional）にする かつては必ず存在していたフィールドが、時折 null になるようになります。クライアント側のコードは、その処理を試みた際にクラッシュします。 安全な対応策: 「常に存在する」ことを一つの約束（プロミス）として扱います。フィールドが任意になる場合は、新しいバージョンを使用してください。

• 未使用のフィールドの削除 コンシューマー（利用者）がどのようにデータを使用しているかを、あなたは把握できていません。「未使用」とは、単に「あなたが使っていない」という意味に過ぎません。 安全な対応策: 何かを削除する前に、本番環境でのフィールドの使用状況を測定してください。

• 入力型の絞り込み 文字列（string）を列挙型（enum）に変えたり、数値（number）を整数（integer）に変えたりすると、リクエストが失敗します。入力の幅を広げることは安全ですが、狭めることは破壊的な変更になります。 安全な対応策: 受け入れる入力を緩和（拡張）することだけを行ってください。制限を厳しくする場合は、新しいバージョンが必要です。

• デフォルト値の変更 デフォルト値を false から true に変更すると、エラーを出さずに挙動が変わってしまいます。これにより、ロジックが静かに壊れます。 安全な対応策: デフォルト値の変更は、破壊的な変更として扱ってください。

• 必須フィールドの追加 tenantId を追加して必須にすると、既存のすべてのクライアントが壊れます。彼らは 400 エラーを受け取ることになります。 安全な対応策: 新しいフィールドは任意にするか、新しいバージョンを使用してください。

• エラー形式の変更 400 を 422 に変えたり、エラーボディの構造を変えたりすると、エラーハンドリングのコードが壊れます。 安全な対応策: エラー形式は「契約（Contract）」です。他のものと同様に、バージョン管理を行ってください。

• Enum（列挙型）の値の変更 "active" を "ACTIVE" にリネームするとクライアントが壊れます。値を削除すると、厳密なロジックを持つクライアントが壊れます。 安全な対応策: Enum の値は不変（forever）であると考えてください。慎重に追加しましょう。メジャーバージョンを上げることなく、リネームや削除を行ってはいけません。

• データ定義（意味）の変更 日付の形式を Unix 秒から ISO-8601 に変えたり、ページネーションを offset から cursor に変えたりすると、すべてが壊れます。スキーマの差分（diff）だけでは、これらに気づけないことさえあります。 安全な対応策: フォーマットを明示的に固定してください。仕様書（spec）だけでなく、実際のペイロードを比較してください。

勘に頼ってはいけません。CIにおいて、すべての変更を本番環境のコントラクトと比較してください。人間はフィールド名の変更を見逃すことがありますが、diffツールなら見逃しません。

出典: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0