はじめに
- 最近、APIのバージョニングについて考えることがあったので自分なりに調べたことを下記にまとめる。
APIにバージョンを含めるメリット・デメリット
メリット
クライアント側が特定のバージョンを指定してアクセスすることができるので、クライアント側がバージョンアップに伴い仕様変更やバージョンアップによるエラーが発生しなくなる。
デメリット
複数バージョンを並列稼働させるため、ソースコードやデータベースの管理が分岐される。サーバーのコストと各バージョンを運用・テストするコストがかかる
＜所感＞
広く世間一般に公開するようなサービスを展開するのであれば、利用者の利便性を考慮してAPIバージョンを含めたURL設計を行った方が良いが、内部システムのAPIの場合、メージャーバージョンのアップデート時に新旧バージョンを並列で稼働させるぐらいで、新しいバージョンに切り替えたら古いバージョンを削除するだけなので、バージョン管理は不要な気がする。
APIバージョンを管理する方法
1.URIパスによるバージョン管理
例
http://www.example.com/api/v1/
長所
クライアントはリソースをキャッシュできる
2.クエリパラメータによるバージョン管理
- クエリパラメーターとしてバージョン番号を含めることです。
例
http://www.example.com/api/?version=1
長所
クエリーがなければ最新APIのバージョンで動作させる。もしクライアント側でバージョン指定したい場合、クエリパラメータを付けてリクエストしてもらう
3.カスタムヘッダーによるバージョン管理
- バージョン番号が含まれるカスタムヘッダーをリクエストしてもらう
curl http://www.example.com/api/ -H X-Api-Version：1.0
※ X-接続辞が2012年6月以降は非推奨になっている。
長所： クエリ同様に指定のバージョンがヘッダーになければ最新バージョンのAPIを実行し、指定のバージョンで実行したい場合、クライアントにバージョンを指定してもらう。
freeeのAPIはx-api-versionのヘッダーを指定してる developer.freee.co.jp
バージョンの付け方
メジャー
後方互換しない修正
マイナー
後方互換する機能追加
パッチ
後方互換するバグ修正
バージョニングをしてくるJSのパッケージ
- koa.js用
- strapi用
※何か良い方法がありましたら、教えてください。
