Web APIのバージョン管理について

書籍 Web API Good Parts

5.2 APIをバージョンで管理する

やり方の例

• 5.2.1 URIのバージョンを埋め込む
• 5.2.3 バージョンをクエリ文字列に入れる
• 5.2.4 メディアタイプでバージョンを指定する

どれを選ぶか

5.2.5 どの方法を採用すべきか

• 最もメジャーなのは、URIに埋め込む方式
  • こだわりがなければこれが無難
• メディアタイプで指定する方法はHTTPの仕組みを最も正しく使っているが、わかりやすさや普及度から考えるとうーん。
  • Googleでこの形式からURI形式に変更した例がある

5.3 バージョンを変える際の指針

前提としてバージョンを増やすことは、提供側/利用側双方のメンテナンスコストを増加させる。
なので

• 基本はマイナーバージョンアップ
  • 軽微な変更でバージョンを上げるべきではない
• 後方互換性を保つことが難しい場合のみバージョンを上げる
• 考え方の例：genderという項目について、数値（1:男性 2:女性 など）から、Enum文字列（male, female）で扱う方針に変えた場合
  • 数値を文字列に変えると後方互換性が消えてしまう。
  • 数値管理のgenderは残しつつgenderStr的な新しい項目を増やして対応し、genderには後のバージョンアップで削除予定である旨をドキュメントに付しておく