feat(api): add /api/v2 namespace falling back to v1

## Context

The product-catalog work introduces a second API version. A v2 client
should use /api/v2 for its whole integration without mixing in v1, even for
resources that have not been reimplemented yet.

## Description

Extract the shared API resource definitions into a draw(:shared_api) file
used by both namespaces. The v1 namespace draws them as today; a new v2
namespace draws the same set with module: :v1, so every /api/v2 path is
served by the existing Api::V1 controller until a real Api::V2 controller
replaces it. Add a routing parity spec asserting every v1 endpoint is
reachable under v2, plus a request smoke test.

Author: rsempe

config/routes.rb

@@ -27,184 +27,11 @@
 
   namespace :api do
     namespace :v1 do
-      resources :activity_logs, param: :activity_id, only: %i[index show]
-      resources :api_logs, param: :request_id, only: %i[index show]
-      resources :security_logs, param: :log_id, only: %i[index show]
-
-      namespace :analytics do
-        get :gross_revenue, to: "gross_revenues#index", as: :gross_revenue
-        get :invoiced_usage, to: "invoiced_usages#index", as: :invoiced_usage
-        get :invoice_collection, to: "invoice_collections#index", as: :invoice_collection
-        get :mrr, to: "mrrs#index", as: :mrr
-        get :overdue_balance, to: "overdue_balances#index", as: :overdue_balance
-      end
-
-      get "analytics/usage", to: "data_api/usages#index", as: :usage
-
-      resources :billing_entities, param: :code, only: %i[index show update create]
-
-      resources :customers, param: :external_id, only: %i[create index show destroy] do
-        get :portal_url
-
-        get :current_usage, to: "customers/usage#current"
-        get :projected_usage, to: "customers/projected_usage#current"
-        get :past_usage, to: "customers/usage#past"
-
-        post :checkout_url
-
-        scope module: :customers do
-          resources :applied_coupons, only: %i[index destroy]
-          resources :credit_notes, only: %i[index]
-          resources :invoices, only: %i[index]
-          resources :payments, only: %i[index]
-          resources :payment_requests, only: %i[index]
-          resources :subscriptions, only: %i[index]
-          resources :wallets, only: %i[create update show index], param: :code do
-            scope module: :wallets do
-              resources :alerts, only: %i[create index update show destroy], param: :code do
-                collection do
-                  delete "/", action: :destroy_all
-                end
-              end
-              resource :metadata, only: %i[create update destroy] do
-                delete ":key", action: :destroy_key, on: :member
-              end
-            end
-          end
-          delete "/wallets/:code", to: "wallets#terminate"
-          resources :payment_methods, only: %i[index destroy] do
-            put :set_as_default, on: :member
-          end
-        end
-      end
-
-      resources :subscriptions, only: %i[create update show index], param: :external_id do
-        resource :lifetime_usage, only: %i[show update], controller: "subscriptions/lifetime_usages"
-        resources :alerts, only: %i[create index update show destroy], param: :code, controller: "subscriptions/alerts" do
-          collection do
-            delete "/", action: :destroy_all
-          end
-        end
-        resources :entitlements, only: %i[index destroy], param: :code, code: /.*/, controller: "subscriptions/entitlements" do
-          resources :privileges, only: %i[destroy], param: :code, code: /.*/, controller: "subscriptions/entitlements/privileges"
-        end
-        patch :entitlements, to: "subscriptions/entitlements#update"
-        resources :fixed_charges, only: %i[index show update], param: :code, code: /.*/, controller: "subscriptions/fixed_charges"
-        resources :charges, only: %i[index show update], param: :code, code: /.*/, controller: "subscriptions/charges" do
-          resources :filters, only: %i[index show create update destroy], controller: "subscriptions/charges/filters"
-        end
-      end
-      delete "/subscriptions/:external_id", to: "subscriptions#terminate", as: :terminate
-
-      resources :add_ons, param: :code, code: /.*/
-      resources :billable_metrics, param: :code, code: /.*/ do
-        post :evaluate_expression, on: :collection
-      end
-
-      resources :features, param: :code, code: /.*/, only: %i[index show create update destroy] do
-        scope module: :features do
-          resources :privileges, only: %i[destroy], param: :code
-        end
-      end
-
-      resources :coupons, param: :code, code: /.*/
-      resources :credit_notes, only: %i[create update show index] do
-        post :download, on: :member, action: :download_pdf
-        post :download_pdf, on: :member
-        post :download_xml, on: :member
-        post :resend_email, on: :member
-        put :void, on: :member
-        post :estimate, on: :collection
-        scope module: :credit_notes do
-          resource :metadata, only: %i[create update destroy] do
-            delete ":key", action: :destroy_key, on: :member
-          end
-        end
-      end
-      get :events_enriched, to: "events#index_enriched"
-      resources :events, only: %i[create show index], constraints: {id: /[^\/]+/} do
-        post :estimate_fees, on: :collection
-        post :estimate_instant_fees, on: :collection
-        post :batch_estimate_instant_fees, on: :collection
-      end
-      resources :applied_coupons, only: %i[create index]
-      resources :fees, only: %i[show update index destroy]
-      resources :invoices, only: %i[create update show index] do
-        post :download, on: :member, action: :download_pdf
-        post :download_pdf, on: :member
-        post :download_xml, on: :member
-        post :resend_email, on: :member
-        post :void, on: :member
-        post :lose_dispute, on: :member
-        post :retry, on: :member
-        post :retry_payment, on: :member
-        post :payment_url, on: :member
-        post :preview, on: :collection
-        put :refresh, on: :member
-        put :finalize, on: :member
-        put :sync_salesforce_id, on: :member
-      end
-      resources :payment_receipts, only: %i[index show] do
-        post :resend_email, on: :member
-      end
-      resources :payment_requests, only: %i[create index show]
-      resources :order_forms, only: %i[show index] do
-        post :mark_as_signed, on: :member
-        post :void, on: :member
-      end
-
-      resources :quotes, only: %i[index show] do
-        resources :versions, only: %i[index], controller: "quotes/versions"
-      end
-      resources :quote_versions, only: %i[show] do
-        post :approve, on: :member
-        post :void, on: :member
-        post :clone, on: :member
-      end
-
-      resources :orders, only: %i[show index]
-      resources :payments, only: %i[create index show]
-      resources :plans, param: :code, code: /.*/ do
-        resources :charges, only: %i[index show create update destroy], param: :code, code: /.*/, controller: "plans/charges" do
-          resources :filters, only: %i[index show create update destroy], controller: "plans/charges/filters"
-        end
-        resources :fixed_charges, only: %i[index show create update destroy], param: :code, code: /.*/, controller: "plans/fixed_charges"
-        resources :entitlements, only: %i[index show create destroy], param: :code, code: /.*/, controller: "plans/entitlements" do
-          resources :privileges, only: %i[destroy], param: :code, code: /.*/, controller: "plans/entitlements/privileges"
-        end
-        patch :entitlements, to: "plans/entitlements#update"
-        scope module: :plans do
-          resource :metadata, only: %i[create update destroy] do
-            delete ":key", action: :destroy_key, on: :member
-          end
-        end
-      end
-      resources :taxes, param: :code, code: /.*/
-      resources :wallet_transactions, only: %i[create show] do
-        post :payment_url, on: :member
-        get :consumptions, on: :member
-        get :fundings, on: :member
-      end
-      get "/wallets/:id/wallet_transactions", to: "wallet_transactions#index"
-      resources :wallets, only: %i[create update show index] do
-        scope module: :wallets do
-          resource :metadata, only: %i[create update destroy] do
-            delete ":key", action: :destroy_key, on: :member
-          end
-        end
-      end
-      delete "/wallets/:id", to: "wallets#terminate"
-      post "/events/batch", to: "events#batch"
-
-      get "/organizations", to: "organizations#show"
-      put "/organizations", to: "organizations#update"
-      get "/organizations/grpc_token", to: "organizations#grpc_token"
+      draw(:shared_api)
+    end
 
-      resources :webhook_endpoints, only: %i[create index show destroy update]
-      resources :webhooks, only: %i[] do
-        get :public_key, on: :collection
-        get :json_public_key, on: :collection
-      end
+    namespace :v2, module: :v1 do
+      draw(:shared_api)
     end
 
     namespace :v2 do

config/routes/shared_api.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+resources :activity_logs, param: :activity_id, only: %i[index show]
+resources :api_logs, param: :request_id, only: %i[index show]
+resources :security_logs, param: :log_id, only: %i[index show]
+
+namespace :analytics do
+  get :gross_revenue, to: "gross_revenues#index", as: :gross_revenue
+  get :invoiced_usage, to: "invoiced_usages#index", as: :invoiced_usage
+  get :invoice_collection, to: "invoice_collections#index", as: :invoice_collection
+  get :mrr, to: "mrrs#index", as: :mrr
+  get :overdue_balance, to: "overdue_balances#index", as: :overdue_balance
+end
+
+get "analytics/usage", to: "data_api/usages#index", as: :usage
+
+resources :billing_entities, param: :code, only: %i[index show update create]
+
+resources :customers, param: :external_id, only: %i[create index show destroy] do
+  get :portal_url
+
+  get :current_usage, to: "customers/usage#current"
+  get :projected_usage, to: "customers/projected_usage#current"
+  get :past_usage, to: "customers/usage#past"
+
+  post :checkout_url
+
+  scope module: :customers do
+    resources :applied_coupons, only: %i[index destroy]
+    resources :credit_notes, only: %i[index]
+    resources :invoices, only: %i[index]
+    resources :payments, only: %i[index]
+    resources :payment_requests, only: %i[index]
+    resources :subscriptions, only: %i[index]
+    resources :wallets, only: %i[create update show index], param: :code do
+      scope module: :wallets do
+        resources :alerts, only: %i[create index update show destroy], param: :code do
+          collection do
+            delete "/", action: :destroy_all
+          end
+        end
+        resource :metadata, only: %i[create update destroy] do
+          delete ":key", action: :destroy_key, on: :member
+        end
+      end
+    end
+    delete "/wallets/:code", to: "wallets#terminate"
+    resources :payment_methods, only: %i[index destroy] do
+      put :set_as_default, on: :member
+    end
+  end
+end
+
+resources :subscriptions, only: %i[create update show index], param: :external_id do
+  resource :lifetime_usage, only: %i[show update], controller: "subscriptions/lifetime_usages"
+  resources :alerts, only: %i[create index update show destroy], param: :code, controller: "subscriptions/alerts" do
+    collection do
+      delete "/", action: :destroy_all
+    end
+  end
+  resources :entitlements, only: %i[index destroy], param: :code, code: /.*/, controller: "subscriptions/entitlements" do
+    resources :privileges, only: %i[destroy], param: :code, code: /.*/, controller: "subscriptions/entitlements/privileges"
+  end
+  patch :entitlements, to: "subscriptions/entitlements#update"
+  resources :fixed_charges, only: %i[index show update], param: :code, code: /.*/, controller: "subscriptions/fixed_charges"
+  resources :charges, only: %i[index show update], param: :code, code: /.*/, controller: "subscriptions/charges" do
+    resources :filters, only: %i[index show create update destroy], controller: "subscriptions/charges/filters"
+  end
+end
+delete "/subscriptions/:external_id", to: "subscriptions#terminate", as: :terminate
+
+resources :add_ons, param: :code, code: /.*/
+resources :billable_metrics, param: :code, code: /.*/ do
+  post :evaluate_expression, on: :collection
+end
+
+resources :features, param: :code, code: /.*/, only: %i[index show create update destroy] do
+  scope module: :features do
+    resources :privileges, only: %i[destroy], param: :code
+  end
+end
+
+resources :coupons, param: :code, code: /.*/
+resources :credit_notes, only: %i[create update show index] do
+  post :download, on: :member, action: :download_pdf
+  post :download_pdf, on: :member
+  post :download_xml, on: :member
+  post :resend_email, on: :member
+  put :void, on: :member
+  post :estimate, on: :collection
+  scope module: :credit_notes do
+    resource :metadata, only: %i[create update destroy] do
+      delete ":key", action: :destroy_key, on: :member
+    end
+  end
+end
+get :events_enriched, to: "events#index_enriched"
+resources :events, only: %i[create show index], constraints: {id: /[^\/]+/} do
+  post :estimate_fees, on: :collection
+  post :estimate_instant_fees, on: :collection
+  post :batch_estimate_instant_fees, on: :collection
+end
+resources :applied_coupons, only: %i[create index]
+resources :fees, only: %i[show update index destroy]
+resources :invoices, only: %i[create update show index] do
+  post :download, on: :member, action: :download_pdf
+  post :download_pdf, on: :member
+  post :download_xml, on: :member
+  post :resend_email, on: :member
+  post :void, on: :member
+  post :lose_dispute, on: :member
+  post :retry, on: :member
+  post :retry_payment, on: :member
+  post :payment_url, on: :member
+  post :preview, on: :collection
+  put :refresh, on: :member
+  put :finalize, on: :member
+  put :sync_salesforce_id, on: :member
+end
+resources :payment_receipts, only: %i[index show] do
+  post :resend_email, on: :member
+end
+resources :payment_requests, only: %i[create index show]
+resources :order_forms, only: %i[show index] do
+  post :mark_as_signed, on: :member
+  post :void, on: :member
+end
+
+resources :quotes, only: %i[index show] do
+  resources :versions, only: %i[index], controller: "quotes/versions"
+end
+resources :quote_versions, only: %i[show] do
+  post :approve, on: :member
+  post :void, on: :member
+  post :clone, on: :member
+end
+
+resources :orders, only: %i[show index]
+resources :payments, only: %i[create index show]
+resources :plans, param: :code, code: /.*/ do
+  resources :charges, only: %i[index show create update destroy], param: :code, code: /.*/, controller: "plans/charges" do
+    resources :filters, only: %i[index show create update destroy], controller: "plans/charges/filters"
+  end
+  resources :fixed_charges, only: %i[index show create update destroy], param: :code, code: /.*/, controller: "plans/fixed_charges"
+  resources :entitlements, only: %i[index show create destroy], param: :code, code: /.*/, controller: "plans/entitlements" do
+    resources :privileges, only: %i[destroy], param: :code, code: /.*/, controller: "plans/entitlements/privileges"
+  end
+  patch :entitlements, to: "plans/entitlements#update"
+  scope module: :plans do
+    resource :metadata, only: %i[create update destroy] do
+      delete ":key", action: :destroy_key, on: :member
+    end
+  end
+end
+resources :taxes, param: :code, code: /.*/
+resources :wallet_transactions, only: %i[create show] do
+  post :payment_url, on: :member
+  get :consumptions, on: :member
+  get :fundings, on: :member
+end
+get "/wallets/:id/wallet_transactions", to: "wallet_transactions#index"
+resources :wallets, only: %i[create update show index] do
+  scope module: :wallets do
+    resource :metadata, only: %i[create update destroy] do
+      delete ":key", action: :destroy_key, on: :member
+    end
+  end
+end
+delete "/wallets/:id", to: "wallets#terminate"
+post "/events/batch", to: "events#batch"
+
+get "/organizations", to: "organizations#show"
+put "/organizations", to: "organizations#update"
+get "/organizations/grpc_token", to: "organizations#grpc_token"
+
+resources :webhook_endpoints, only: %i[create index show destroy update]
+resources :webhooks, only: %i[] do
+  get :public_key, on: :collection
+  get :json_public_key, on: :collection
+end

spec/requests/api/v2/fallback_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe "API v2 fallback to v1" do
+  let(:organization) { create(:organization) }
+
+  it "serves a v1-backed resource under /api/v2" do
+    plan = create(:plan, organization:)
+
+    get_with_token(organization, "/api/v2/plans")
+
+    expect(response).to have_http_status(:success)
+    expect(json[:plans].map { it[:lago_id] }).to include(plan.id)
+  end
+end