自社のECサイトからアクセスされるAPIのバージョンの管理についていろいろ調べて悩んだので共有します。
課題:
自社ECサイトのAPIとフロントエンドアプリケーションのリリースと切り戻しを独立させたい
(APIは社内のフロントエンドアプリケーションからしか利用されていません。)
状況:
・バックエンドのAPIはフロンドエンドのアプリケーションからのみ参照されていてそれ以外はない。
・現状はリリースする際に、フロントエンドとバックエンドのリリースタイミングを調整してリリースしている。
・apiを先にリリースしなければならないのはしかたないが、切り戻しが必要になった時などにフロントだけ切り戻せばすむようにしたい。
->下位互換でapiをつくればいいが、すぐに不要になる下位互換性のためにどんどんコードがよごれていくのはいや。
->リリース終わってしばらくしたら、下位互換のコードを削除というのもまたテスト必要になって不便。
ということでうまいことバージョンを管理したい。
解決方法案:
1. 下位互換がある形でつくる。リリースしてしばらくしたら、下位互換のためのコードを削除
下位互換でつくったものを技術負債を解消するために後から下位互換のためのコードを削除するというのは
テストも含めて手間。多分放置される。
2. URLにバージョンを付加し、互換性のない変更がある場合はバージョンをあげていく
https://api.company.com/v1/users/1
良さそう。
3. ヘッダーにバージョンを付加する
既存のヘッダーにバージョンが付加されていないものはどうするか?という問題がある。
バージョンがない場合は最新のバージョンと判断するということもできるがそれだと、api側でーバージョンをあげた場合に
バージョン指定がないリクエストはフロント側でも急にバージョンがあがってしまうのでよくない。
解決方法案3つ検討しましたがどうやら2のURLにバージョンを付加するというのが一番良さそうな気がします。
ここからは2の選択肢について検討したことを見ていきます。
・ バージョン毎にコントローラを作成するのか?
API::V2::UsersController などのようにバージョン毎にコントローラを作成するのが正しいような気もします。
ただ現状だと古いバージョンはなる早で消していき古いコントローラもすぐに消してしまうと思うので今回の場合はコントローラは一つで良いと判断しました。
・ ルートによってバージョンがv1だったりv2だったりしたらごちゃごちゃしてわかりにくいのでは?
フロントチームが開発をするときやテスト用にURLをブックマークしていたりする他のapi開発者とかもバージョンが変わることで
混乱する可能性はあります。がしかし、コードに互換性を持たせたりそれを削除したりするストレスや手間に比べればたまにurlがわからないくらい
大したことではないでしょう。と判断しました。swaggerやエラーメッセージの利用でなるべくこの辺は改善するようにしましょう。
ということで今回は以下の方針でいくことにしました。
- 互換性のない変更はURLにバージョンを付加する。
- バージョン毎にコントローラをつくったりはしない。すぐ削除するので。
みなさんの参考になれば幸いです。
助言あればぜひお願いします。