API versioning in Ruby on Rails - Mini Project: Build & Apply

API Versioning in Rails

📖 Scenario: You are building a simple Rails API for a bookstore. You want to support multiple versions of your API so that you can improve it later without breaking existing clients.

🎯 Goal: Create a basic Rails API with two versions: v1 and v2. Each version will have a BooksController with an index action that returns a list of books. The v2 version will add a new field to the book data.

📋 What You'll Learn

Create a Book model with title and author attributes

Set up API versioning using namespaces v1 and v2 in routes

Implement BooksController in both versions with an index action

In v1, return title and author for each book

In v2, return title, author, and a new published_year field

💡 Why This Matters

🌍 Real World

API versioning is essential when you want to improve or change your API without breaking existing clients. Many companies use versioning to support old and new app versions simultaneously.

💼 Career

Understanding API versioning in Rails is important for backend developers working on web services, ensuring smooth upgrades and backward compatibility.

1

Create the Book model with attributes

Create a Rails model called Book with string attributes title and author. Add a migration to create the books table with these columns.

Ruby on Rails

# Generate Book model with title and author attributes
# Your code here

Need a hint?

Use rails generate model Book title:string author:string to create the model and migration.

2

Set up API versioning namespaces in routes

In config/routes.rb, create two namespaces: v1 and v2. Inside each namespace, add a resource route for books with only the index action.

Ruby on Rails

class Book < ApplicationRecord
end

# Migration file example:
# class CreateBooks < ActiveRecord::Migration[7.0]
#   def change
#     create_table :books do |t|
#       t.string :title
#       t.string :author
#       t.timestamps
#     end
#   end
# end

Rails.application.routes.draw do
  # Add API version namespaces and books routes here
  # Your code here
end

Need a hint?

Use namespace :v1 do ... end and namespace :v2 do ... end blocks in routes.

3

Implement BooksController with index action for v1

Create V1::BooksController with an index action that fetches all books and renders JSON with only title and author fields.

Ruby on Rails

class Book < ApplicationRecord
end

Rails.application.routes.draw do
  namespace :v1 do
    resources :books, only: [:index]
  end

  namespace :v2 do
    resources :books, only: [:index]
  end
end

module V1
  class BooksController < ApplicationController
    # Add index action here
    # Your code here
  end
end

Need a hint?

Use render json: books.as_json(only: [:title, :author]) to limit fields.

4

Implement BooksController with index action for v2 with extra field

Create V2::BooksController with an index action that fetches all books and renders JSON with title, author, and published_year fields. Add published_year as a string attribute to the Book model migration.

Ruby on Rails

class Book < ApplicationRecord
end

Rails.application.routes.draw do
  namespace :v1 do
    resources :books, only: [:index]
  end

  namespace :v2 do
    resources :books, only: [:index]
  end
end

module V1
  class BooksController < ApplicationController
    def index
      books = Book.all
      render json: books.as_json(only: [:title, :author])
    end
  end
end

module V2
  class BooksController < ApplicationController
    # Add index action here
    # Your code here
  end
end

Need a hint?

Remember to add published_year column to the books table and include it in the JSON response.