One of the scariest things about maintaining a production API is the "breaking change." You want to rename a field for clarity or restructure a JSON response to be more efficient, but you know that the second you deploy that change, every mobile app or third-party integration relying on your API will start crashing. This is why we version.

In Rails, there are a few ways to handle this—via headers, query parameters, or URL paths. I've always found URL namespacing (e.g., /api/v1/books) to be the most transparent and easiest to debug. Let's build a small Book Catalog API to see how this works in practice.

Defining the first stable version

Let's assume we have a Book model. For our first version, we'll keep it simple. I want the API to return a list of books with their titles and the author's name.

First, I'll set up the routes. I'm wrapping everything in an api scope and then a v1 namespace:

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :books, only: [:index, :show]
    end
  end
end

Now, I'll create the controller. Since it's namespaced, the file needs to live in app/controllers/api/v1/books_controller.rb and the class must be nested within the corresponding modules.

# app/controllers/api/v1/books_controller.rb
module Api
  module V1
    class BooksController < ApplicationController
      def index
        @books = Book.all
        render json: @books.map { |b| { title: b.title, author_name: b.author } }
      end
    end
  end
end

The "Oops" moment: Namespace Mismatches

I've done this a hundred times, and I still do it: I just tried to run a request to /api/v1/books and got a AbstractController::ActionNotFound error. I looked at my controller and realized I had named the class BooksController but I forgot to wrap it in the module Api and module V1 blocks in the actual file. Rails is very strict about the directory structure matching the module nesting. If the file is in api/v1/, the class must be Api::V1::BooksController.

I fixed the nesting (as shown in the code block above), and suddenly, everything worked. Always check your module nesting first when you see a "Controller not found" error in a namespaced route.

Introducing V2 without breaking V1

Now, imagine the business requirements change. We want the API to return a summary of the book, and we've realized that author_name is redundant—we just want to call it author. If I change V1, I break the old apps. Instead, I'll spin up V2.

I'll add the new namespace to my routes:

# config/routes.rb
namespace :api do
  namespace :v1 do
    resources :books, only: [:index, :show]
  end
  namespace :v2 do
    resources :books, only: [:index, :show]
  end
end

Then, I create a new controller at app/controllers/api/v2/books_controller.rb. To keep things DRY, I could inherit from the V1 controller, but usually, when you're versioning, the logic diverges enough that it's cleaner to just inherit from ApplicationController and share logic via Concerns if needed.

# app/controllers/api/v2/books_controller.rb
module Api
  module V2
    class BooksController < ApplicationController
      def index
        @books = Book.all
        # In V2, we rename author_name to author and add summary
        render json: @books.map { |b| { 
          title: b.title, 
          author: b.author, 
          summary: b.summary 
        } }
      end
    end
  end
end

Now we have two parallel universes. Old clients hit /api/v1/books and get the old format. New clients hit /api/v2/books and get the updated data. I can now monitor the V1 logs, and once I see that traffic has dropped to zero, I can safely delete the v1 folder and routes.

📋 Practical Task

Exercise: Implementing V2 for the User Profile API

You are maintaining a User Profile API. Currently, v1 of the UsersController returns a single field: full_name.

Your task is to implement v2 of this API. In v2, the full_name field should be removed and replaced with two separate fields: first_name and last_name. Additionally, v2 should include a member_since date.

• Update config/routes.rb to include the v2 namespace for users.
• Create the Api::V2::UsersController in the correct directory.
• Implement the show action in v2 to return the new JSON structure (first_name, last_name, member_since).
• Ensure that Api::V1::UsersController remains untouched and continues to return full_name.