APIバージョニング とは？

たとえば返却するnameという項目を削除すると、それを読むアプリが動かなくなるかもしれない。互換性に影響する変更を扱うため、旧仕様と新仕様を別の版として提供する方法があるよ。番号を付けるだけで安全になるのではなく、版ごとの約束を守ることが大切なんだ。

パスで/api/v1/usersのように示す方式や、ヘッダーで指定する方式があるよ。GoogleのAPI設計指針はRESTのパスに主要な版を含める。一方GitHubのREST APIはX-GitHub-Api-Versionヘッダーに公開日形式の版を指定する。どのAPIでも同じ書き方ではないんだ。

必ずしもそうではないよ。提供元が互換性を保てると判断した追加は、同じ版に入ることもある。GitHubの資料でも、項目の削除や型変更と、任意パラメータなどの追加を区別している。利用する側も、追加項目で壊れない扱いになっているかを確かめよう。

提供期間はAPIごとの方針次第だよ。終了予定があれば、変更点と移行手順を確認して、利用する版やアプリを更新する。非推奨の案内と、完全に停止する日は別の意味になる場合もある。既定の版に任せきりだと、その切り替えの影響を受ける可能性もあるね。

返却される型、必須項目、認証条件などの変更を読んで、アプリが動くかテストするよ。新旧を提供する期間を使い、利用者が段階的に移れるようにする。方式の選択だけでなく、互換性の方針と終了時の案内まで含めて運用しよう。