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.