Version API

Implement versioning strategies for Rails APIs.

Quick Reference

HARD-GATE

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

Core Process

1. Choose strategy — URL path (/api/v1/) for public APIs; Accept header for internal/private APIs. See strategies.md for header-based versioning details and trade-offs.
2. Add route namespace — Wrap new version resources in a namespace :v2 block in config/routes.rb:

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

3. Create controllers — Inherit from the previous version's controller and override only changed actions:

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

   See EXAMPLES.md for additional inheritance patterns.
4. Apply deprecation — Include Deprecatable in old-version controllers to emit Sunset and Deprecation response headers automatically via a before_action:

   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. Run compatibility specs — Execute bundle exec rspec spec/requests/api/backward_compatibility_spec.rb to confirm no regressions before merging.
6. Update documentation — Record the sunset date and migration guide for deprecated endpoints. See workflow.md for the full deprecation communication workflow.

Output Style

1. Define versioning strategy explicitly.
2. Document inheritance strategy.
3. Show route definition and deprecation headers.
4. Include compatibility specs to prevent breakage.
5. Language — Must be in English unless explicitly requested otherwise.

Integration