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

Core Process

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.

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

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.

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

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

Output Style

When asked to implement API versioning, your output MUST include:

Versioning strategy — Explicitly state whether using URL path (/api/v1/) or Accept header versioning
Inheritance strategy — Document how new version controllers inherit from previous version
Route definition — Show the namespace route configuration in config/routes.rb
Deprecation headers — Include Deprecatable concern with sunset date configuration
Compatibility specs — Include the command to run backward compatibility specs
Language — Must be in English unless explicitly requested otherwise

Extended Resources (Progressive Disclosure)

Load these files only when their specific content is needed:

EXAMPLES.md — Use when you need complete API versioning examples with route definitions and controller inheritance
references/strategies.md — Use when comparing versioning strategies (URL path vs header vs query param)
references/workflow.md — Use when implementing the deprecation communication workflow and sunset scheduling

Integration

Skill	When to chain
generate-api-collection	When generating the updated API endpoints
test-engine	When verifying specs for regressions

Concern	File
Route namespaces	`config/routes.rb`
Header versioning	`app/controllers/concerns/api_versioning.rb`
Deprecation headers	`app/controllers/concerns/deprecatable.rb`
Compatibility specs	`spec/requests/api/backward_compatibility_spec.rb`

version-api

Version API

Quick Reference

HARD-GATE