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

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

後方互換性を保つことが可能な変更は、可能な限り同じバージョンでのマイナーバージョンアップで対応し、どうしても後方互換性を保ったまま修正を行うことが難しい場合のみ にバージョンを上げるべき。

データ名の変更や形式の変更等ではバージョンは上げない。ドキュメント等に古いやり方はバージョンアップの際に廃止される旨を記載し、古い項目の利用時に注意できるようにする。

後方互換性を保たなくてよい変更の例

• セキュリティや権限などのルールを変更した場合
  (認証を追加する・ベーシック認証を廃止し OAuth のみに変更する等)
• 開発初期の API 等のルール未整理のまま拡大した API の整理等

5.3.1 常に最新版を返すエイリアスは必要か

基本的には不要。同じ方法でのアクセスで挙動が変化する可能性があるのは、利用者側からしてみれば利用しづらい。