新しい機能を実装したり、機能の要件が変わったりして、APIのインターフェースを更新したい、というケースはよくある。でもそのときに、色々考えないと、システムはぶっ壊れてしまう。
壊れないようにどうするか。フロントエンドもセットでどどんとリリースするか。あるいはバージョニングするか。
ビッグバンリリース
バックエンドの新しいインターフェースを呼び出すよう、フロントエンドも一緒になってリリースをしてしまう作戦。リリース量が大きくなるので怖い感じはある。障害とか。
他にもフロントエンドで強力にキャッシュが効いていて、フロントエンドのコードを更新する手段が限られる、となっているともしかしたら難しいかもしれない。
APIのバージョニング
/v1/foo -> /v2/foo みたいにバージョンをURLに含めるものが割と一般的なイメージがある。特にパブリックな公開されているAPIはこういう印象がある。
HTTPヘッダーでコントロールする方法も考えられる。例えば X-APP-VERSION: 20250101 みたいな。
リクエストパラメータでコントロールするような方法もある。例えば、エンドポイントとしては /foo だけど、リクエストパラメータに version=20250101 を含むとか。
システムのバージョニング
いっそのこと、システム全体をバージョニングしてしまう、というのもある。
設定画面や管理画面などでバージョン選択ができるようになっていて、その設定に応じて、フロントエンドもバックエンドも出し分けがされる。
複雑にはなるけれど、プラットフォーム的なアプリケーションであれば、利用者から見たときには、わかりやすいようにも思える。
いつバージョンを上げるのか
基本的には後方互換性が失われたとき、で良いとおもう。 例えば、エンドポイントが変わる、既存のフィールドの名前や型を変更する、既存のフィールドを削除する、など。
とはいえシステムによっては、未知のフィールドが入っていたらエラーにする、みたいな作りをすることがあるので、方針しだい。
どうバージョンをつけるのか
いわゆるセマンティックバージョニング、v1.0.0 みたいなものは管理するのが難しい。少なくともどんな更新がパッチで、マイナーで、メジャーなのかを定める必要がある。
/v1/foo -> /v2/foo みたいなものも同様。何があったらv2になるのか。
日付をつけるのはどうか？ /20250101/foo -> /20250401/foo これは考えることが少なくてわかりやすい。システムのリリースを行った日（!=デプロイをした日）をつければいいので、どうバージョンをつけるのか気にしなくていい。
合体してもいい。2025年の1回目のリリースなので、202501 (2025.01とか）にするなど。
クリアに決まっていればそれでいいと思う。