API Versioning, without a Bridge version

Problem Statement & Solution Document for "API Versioning, wihtout a Bridge version"

Reality?

Currently, the API lacks a versioning schema. Deploying any breaking changes to the existing "legacy" endpoints would immediately disrupt service for all current users, leading to integration failures and loss of trust.

Consequences?

Without a structured versioning path, we are trapped in a "frozen" state where we cannot improve the API without breaking the current user experience.

Future?

Our API should evolve to support new business requirements and improved data structures while providing a seamless experience for existing integrators.

Proposal!

We will implement an immediate versioning jump to move away from technical debt. This involves:

• Retaining the current unversioned endpoints in their "legacy" state to prevent breaking existing users.
• Directly introducing /v1/ as the new standard, which will immediately incorporate the necessary breaking changes and optimized data structures.

# config/routes.rb
Rails.application.routes.draw do
  
  # 1. Modern API, A.K.A. new standard with breaking changes
  namespace :v1 do
    resources :users # New logic, optimized structures
  end

  # 2. Legacy Support A.K.A. the "Frozen" API
  resources :users, only: [:index, :show]
end

# app/controllers/users_controller.rb
class UsersController < ApplicationController
  def index
    @list = if params[:prefix]
              User.where('login LIKE ?', "#{params[:prefix]}%")
            elsif params[:confirmed]
              User.confirmed
            else
              User.not_deleted
            end
  end
end

# app/controllers/v1/users_controller.rb
module v1
  class UsersController < ApplicationController
    def index
      User.not_deleted
    end
  end
end