API versioning in Ruby on Rails - Step-by-Step Execution

Concept Flow - API versioning

Client sends request

↓

Check API version in request

↓

Route to correct controller version

↓

Process request in versioned controller

↓

Send response back to client

The server checks the API version from the client request, routes it to the matching controller version, processes it, and sends back the response.

Execution Sample

Ruby on Rails

namespace :api do
  namespace :v1 do
    resources :books
  end
  namespace :v2 do
    resources :books
  end
end

Defines two API versions (v1 and v2) with separate routes for books.

Execution Table

Step	Request URL	Version Extracted	Controller Routed	Action Executed	Response
1	/api/v1/books	v1	Api::V1::BooksController	index	List of books from v1
2	/api/v2/books	v2	Api::V2::BooksController	index	List of books from v2 with new fields
3	/api/v3/books	v3	No route found	N/A	404 Not Found
4	/api/books	No version	No route found	N/A	404 Not Found

💡 Requests without matching version or route return 404 Not Found.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4
version	nil	v1	v2	v3	nil
controller	nil	Api::V1::BooksController	Api::V2::BooksController	No route	No route
response	nil	List of books from v1	List of books from v2 with new fields	404 Not Found	404 Not Found

Key Moments - 3 Insights

Why does a request to /api/books fail with 404?

Because the routing expects a version namespace like /api/v1 or /api/v2. Without a version, no matching route exists (see execution_table step 4).

What happens if a client requests a version that is not defined, like v3?

The router cannot find a matching controller for v3, so it returns 404 Not Found (see execution_table step 3).

How does Rails know which controller to use for each version?

The version is extracted from the URL namespace (e.g., /api/v1), and Rails routes to the corresponding controller under that namespace (see execution_table steps 1 and 2).

Visual Quiz - 3 Questions

Look at the execution table, what controller handles the request to /api/v2/books?

A Api::V1::BooksController

B Api::V2::BooksController

C No route found

D Api::V3::BooksController

💡 Hint

Check the 'Controller Routed' column for the row with Request URL '/api/v2/books'.

At which step does the version variable become 'v1'?

A After Step 1

B After Step 2

C After Step 3

D After Step 4

💡 Hint

Look at the 'version' row in variable_tracker after each step.

If the client sends a request to /api/v3/books, what response will they get?

A List of books from v3

B List of books from v2

C 404 Not Found

D List of books from v1

💡 Hint

See the 'Response' column in execution_table step 3.

Concept Snapshot

API Versioning in Rails:
- Use namespaces like 'namespace :v1' and 'namespace :v2' in routes.
- Client requests include version in URL (e.g., /api/v1/resource).
- Rails routes to matching versioned controller.
- Requests without matching version return 404.
- Helps maintain multiple API versions simultaneously.

Full Transcript

API versioning in Rails works by defining separate namespaces for each version in the routes file. For example, 'namespace :v1' and 'namespace :v2' create separate paths and controllers for each API version. When a client sends a request, Rails extracts the version from the URL and routes the request to the corresponding controller. If the version is missing or not defined, Rails returns a 404 Not Found error. This approach allows multiple API versions to coexist, so clients can use older or newer versions as needed.

Practice

1. What is the main purpose of API versioning in a Rails application?

easy

A. To change the database schema automatically

B. To allow updates without breaking existing API users

C. To speed up database queries

D. To improve the UI design of the application

Solution

1. Step 1: Understand API versioning concept

   API versioning allows developers to release new API features or changes without affecting users who rely on older versions.

2. Step 2: Identify the main benefit

   This prevents breaking changes and keeps old clients working while new clients can use updated features.

3. Final Answer:

   To allow updates without breaking existing API users -> Option B

4. Quick Check:

   API versioning = safe updates [OK]

Hint: API versioning = safe updates without breaking old clients [OK]

Common Mistakes:

• Thinking it speeds up database queries
• Confusing with UI improvements
• Assuming it changes database schema automatically

2. Which of the following is the correct way to define API versioning in Rails routes using namespaces?

easy

A. version :v1 do
resources :users
end

B. scope :v1 do
resources :users
end

C. namespace :v1 do
resources :users
end

D. api_version :v1 do
resources :users
end

Solution

1. Step 1: Recall Rails routing syntax for versioning

   Rails uses the namespace method to group routes under a version folder like v1.

2. Step 2: Check each option

   Only namespace :v1 do ... end is valid Rails syntax for versioning routes.

3. Final Answer:

   namespace :v1 do resources :users end -> Option C

4. Quick Check:

   Rails versioning uses namespace [OK]

Hint: Use namespace for version folders in routes [OK]

Common Mistakes:

• Using non-existent 'version' or 'api_version' methods
• Using scope without path or module options
• Confusing namespace with scope

3. Given this routes setup in Rails:

namespace :v1 do
  get 'status', to: 'health#show'
end
namespace :v2 do
  get 'status', to: 'health#show'
end

What will GET /v2/status call?

medium

A. The show action in HealthController inside V2 module

B. The show action in the main HealthController without module

C. A routing error because v2 is not defined

D. The show action in HealthController inside V1 module

Solution

1. Step 1: Understand namespace routing effect

   Each namespace creates a module scope. So v2 routes call controllers inside V2:: module.

2. Step 2: Match the route to controller

   GET /v2/status calls V2::HealthController#show, not the v1 or main controller.

3. Final Answer:

   The show action in HealthController inside V2 module -> Option A

4. Quick Check:

   Namespace v2 routes call V2 controllers [OK]

Hint: Namespace URL matches controller module [OK]

Common Mistakes:

• Assuming v2 calls v1 controller
• Thinking it causes routing error
• Ignoring module scoping in namespaces

4. You have this routes file snippet:

namespace :v1 do
  resources :products
end

namespace :v1 do
  resources :orders
end

What is the problem with this code?

medium

A. You must use scope instead of namespace for versioning

B. Rails does not allow multiple namespaces with the same name

C. Resources inside namespaces must be singular, not plural

D. Duplicate namespace declarations can be merged into one block

Solution

1. Step 1: Analyze namespace usage

   Rails allows multiple namespace blocks with the same name but it's better style to merge them.

2. Step 2: Identify best practice

   Merging namespace :v1 blocks into one improves readability and avoids confusion.

3. Final Answer:

   Duplicate namespace declarations can be merged into one block -> Option D

4. Quick Check:

   Merge same namespaces for clarity [OK]

Hint: Merge same namespaces into one block [OK]

Common Mistakes:

• Thinking Rails forbids multiple same namespaces
• Using singular resources incorrectly
• Confusing namespace with scope

5. You want to support two API versions in your Rails app: v1 and v2. v1 returns user data with name only, but v2 adds email. How should you organize your controllers to handle this cleanly?

hard

A. Create separate controllers under app/controllers/v1/users_controller.rb and app/controllers/v2/users_controller.rb with different responses

B. Use a single controller and check version in each action to decide response

C. Put all logic in the model and use one controller for both versions

D. Use middleware to rewrite responses after controller runs

Solution

1. Step 1: Understand version separation best practice

   Separate controllers per version keep code clean and maintainable, avoiding complex conditionals.

2. Step 2: Apply Rails versioning pattern

   Place controllers in versioned folders like v1/users_controller.rb and v2/users_controller.rb to handle different responses.

3. Final Answer:

   Create separate controllers under app/controllers/v1/users_controller.rb and app/controllers/v2/users_controller.rb with different responses -> Option A

4. Quick Check:

   Separate controllers per version = clean code [OK]

Hint: Use separate controllers per version folder [OK]

Common Mistakes:

• Using one controller with many version checks
• Putting version logic in models
• Trying to rewrite responses with middleware