version-api

API バージョニング

Rails API にバージョニング戦略を実装します。

クイックリファレンス

項目	ファイル
ルートの名前空間	config/routes.rb
ヘッダーバージョニング	app/controllers/concerns/api_versioning.rb
非推奨ヘッダー	app/controllers/concerns/deprecatable.rb
互換性スペック	spec/requests/api/backward_compatibility_spec.rb

ハードゲート

GENERATED CODE SAFETY:
- NEVER generate code that constantizes or evaluates caller-supplied version strings
  (e.g. "V#{params[:version]}".constantize is forbidden — use an explicit allowlist).
- NEVER generate code that passes request headers or paths unsanitized into class
  instantiation, eval, or dynamic dispatch.
- Allowlist-only version resolution: generated routing/concern code MUST resolve
  version identifiers from a fixed set (V1, V2, ...), not from free-form input.

ALWAYS maintain backward compatibility for at least one major version
NEVER remove endpoints without deprecation period
ALWAYS version in URL path (/api/v1/) or Accept header, never in body

基本的な手順

1. 戦略を選択する — 公開 API には URL パス（/api/v1/）、内部／プライベート API には Accept ヘッダーを使用します。ヘッダーベースのバージョニングの詳細とトレードオフについては、strategies.md を参照してください。
2. ルートの名前空間を追加する — config/routes.rb の namespace :v2 ブロック内に、新しいバージョンのリソースを記述します。

   namespace :v1 do
     resources :users
   end
   
   namespace :v2 do
     resources :users
   end
   

3. コントローラーを作成する — 以前のバージョンのコントローラーを継承し、変更したアクションのみをオーバーライドします。

   module V2
     class UsersController < V1::UsersController
       def index
         render json: User.all, only: [:id, :name, :email, :phone]
       end
     end
   end
   

   継承パターンの例については、EXAMPLES.md を参照してください。
4. 非推奨化を適用する — 旧バージョンのコントローラーに Deprecatable を含めると、before_action を通じて Sunset ヘッダーと Deprecation レスポンスヘッダーが自動的に出力されます。

   module V1
     class UsersController < ApplicationController
       include Deprecatable
       # Override sunset_date on the class to set the retirement date:
       # def self.sunset_date = Date.new(2025, 6, 1)
     end
   end
   

5. 互換性スペックを実行する — マージ前に bundle exec rspec spec/requests/api/backward_compatibility_spec.rb を実行し、リグレッションがないことを確認します。
6. ドキュメントを更新する — 非推奨エンドポイントのサンセット日と移行ガイドを記録します。非推奨化に関するコミュニケーションの全ワークフローについては、workflow.md を参照してください。

出力形式

API バージョニングの実装を求められた場合、出力には必ず以下を含めてください。

1. バージョニング戦略 — URL パス（/api/v1/）と Accept ヘッダーによるバージョニングのどちらを使用するか明記します
2. 継承戦略 — 新バージョンのコントローラーが以前のバージョンのコントローラーをどのように継承するかを記載します
3. ルート定義 — config/routes.rb の名前空間ルート設定を示します
4. 非推奨ヘッダー — サンセット日の設定を含む Deprecatable concern を記載します
5. 互換性スペック — 後方互換性スペックを実行するコマンドを記載します
6. 言語 — 明示的に別の言語を指定されない限り、英語で記述します

拡張リソース（段階的な情報開示）

特定の内容が必要な場合に限り、以下のファイルを読み込んでください。

• EXAMPLES.md — ルート定義とコントローラー継承を含む、API バージョニングの完全な例が必要な場合に使用します
• references/strategies.md — バージョニング戦略（URL パス、ヘッダー、クエリパラメーター）を比較する場合に使用します
• references/workflow.md — 非推奨化に関するコミュニケーションのワークフローとサンセットのスケジュールを実装する場合に使用します

連携

スキル	連携するタイミング
generate-api-collection	更新された API エンドポイントを生成する場合
test-engine	リグレッションがないかスペックを検証する場合