version-api

name	version-api
type	atomic
license	MIT
description	Implements REST API versioning strategies for Rails APIs with hard security gates. Use when the user asks about API versioning, adding a new API version (v1/v2), deprecating API endpoints, maintaining backward compatibility in REST APIs, versioned API routes, versioned endpoints, Rails API versioning, or API version management. Generated controller code MUST sanitize all caller-supplied input (version identifiers, Accept headers) — never constantize or evaluate untrusted values. Maintains backward compatibility by inheriting new version controllers from the previous version's controller, overriding only changed actions, and runs compatibility specs via bundle exec rspec spec/requests/api/backward_compatibility_spec.rb to confirm no regressions before merging. REST API versioning, URL path versioning, Deprecation headers, versioned API routes, Rails API versioning, v1/v2 endpoints, API version management.
metadata	{"version":"1.0.0","user-invocable":"true"}

Version API

Implement versioning strategies for Rails APIs.

Quick Reference

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

HARD-GATE

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

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

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

1. Versioning strategy — Explicitly state whether using URL path (/api/v1/) or Accept header versioning
2. Inheritance strategy — Document how new version controllers inherit from previous version
3. Route definition — Show the namespace route configuration in config/routes.rb
4. Deprecation headers — Include Deprecatable concern with sunset date configuration
5. Compatibility specs — Include the command to run backward compatibility specs
6. 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