WebAPIの設計〜バージョン管理編〜
Web API: The Good Partsをベースに API の設計するときの
バージョン管理について書いていきたいと思います。
変更しやすい API を設計するにはどのようにすればいいかについて書かれている本です。
バージョン管理の方針
API のバージョンは頻繁に上げてはいけません。
なぜなら、開発者視点とユーザ視点でそれぞれコストがかかるからです。
開発者視点では、メンテナンスコストがかかります。
ユーザ視点では、どのバージョンが最新であるかがわかりにくくなるからです。
なので、セマンティックバージョンで管理するときは、
メジャーバージョンのみを API に表記することで変更を最小限に抑えます。
バージョンの付け方
URI に埋め込む
https://apis.contoso.com/products/v1
"v"は省略可能ですがつけることを推奨します。
理由としては、それがバージョンを表していると把握しやすいためです。
クエリ文字列に入れる
https://apis.contoso.com/products?api-version=v1
パラメータとなっているためバージョン表記を省略可能です。
クエリ文字列に入れる場合、デフォルトのバージョンが固定で設定されていることが多いです。
そのため、ユーザがバージョンを省略して利用すると、予期しないトラブルが起こり得ます。
また、ユーザ目線ではどのバージョンを利用しているか把握しづらいという問題があります。
メディアタイプで指定をする
クライアント側ではリクエストを送るときに Accept ヘッダに指定します。
Accept: application/vnd.examplev2+json
サーバ側では要求されたメディアタイプをもとにレスポンスを生成し、
それをクライアントに返します。
レスポンスを返すときには、Content-Type ヘッダと Vary ヘッダに指定します。
Content-Type:application/vnd.examplev2+json
Vary:Accept
Vary ヘッダはキャッシュを行うときに、データを一意で特定するために URI 以外で
どのリクエストヘッダ項目を利用するかを指定するために必要です。
今回は Accept ヘッダでバージョンを指定しているので"Accept"と指定しています。
おすすめの指定方法
参考書籍によると 1 つ目に紹介した「URI に埋め込む」方法が最もよく利用されているそうです。
ユーザがどのバージョンを利用しているか判断しやすいためだと考えられています。
後方互換性を保つために
gender の項目を「男性の場合は 1、女性の場合は 2」から
「男性の場合は male、女性の場合は female」と変更したいときに
該当箇所を変更してしまうと互換性が保てなくなります。
なので、新しく genderStr という項目を加えてメジャーバージョンが更新されたときに
gender は廃止予定ということをドキュメントに記述します。
API の提供を終了するとき
セキュリティの問題や維持コストの問題で API の提供を終了するときには
下記の方法が挙げられます。
- 事前に周知徹底をする
- 提供終了時の仕様を記載しておく
- 利用規約にサポート期限を明記する
事前に周知徹底をする
参考書籍では Twitter を例に半年かけて API の停止を行う方法が書かれていました。
告知をするだけでなく、URI にバージョン表記を入れないと
アクセスを拒否するようにアップデートをするなど
少しずつ停止を行うためにどのようなことをしてきたかといったことが書かれていました。
提供終了時の仕様を記載しておく
たとえば、ステータスコード 410(gone)を返す、強制アップデートをさせるなどが挙げられます。
利用規約にサポート期限を明記する
新しい API が公開されたときに、12 ヶ月以内に移行しないと
古いバージョンのサポートは終了する可能性があることを利用規約に明記するなどといったことが挙げられます。
Discussion