API設計で api/v1 フォルダを作成する理由

1. バージョニング（APIのバージョン管理）のため

バージョニングとは何か？ APIを公開すると、機能の追加や変更が頻繁に行われます。既存のクライアントに影響を与えず、新しい機能や仕様を提供するためには「バージョン管理」が必要です。

例えば、v1 では在庫情報をシンプルな形式で返していたとします。
新しいクライアントが増え、データ形式を変更する必要がある場合、v2 を作成して新しい形式を提供できます。
古いクライアントは v1 を使い続けることで影響を受けません。
このバージョン管理を行うために、api/v1 というディレクトリ構造を採用します。

2. コードの整理・可読性向上のため

目的ごとのフォルダ分け APIにはさまざまなリソース（例: ユーザー、在庫、注文）が存在します。それぞれのリソースに対応するコントローラーが増えると、1つのフォルダにまとめると非常に管理が難しくなります。

例: フォルダが1層の場合

app/controllers/
├── inventory_controller.rb
├── users_controller.rb
├── orders_controller.rb
└── other_controller.rb

→ コントローラーが増えると、全てが app/controllers 直下に配置され、混乱を招きます。

フォルダを分けた場合

app/controllers/api/v1/
├── inventory_controller.rb
├── users_controller.rb
└── orders_controller.rb

→ APIのエンドポイントを明確にグループ化でき、管理しやすくなります。

3. エンドポイント構造との一致性

APIクライアントから見たとき、URLが以下のようになります。

/inventory（フラット構造）→ バージョン管理がなく、将来の変更が困難。

/api/v1/inventory（階層構造）→ 明確にバージョン管理されており、将来の拡張に柔軟。

このURL構造に合わせてディレクトリを整理することで、URLとディレクトリ構造の対応がわかりやすくなります。

4. RESTful設計の原則に従うため

RESTful設計では、リソースごとに明確なエンドポイントを定義し、それに対応するコントローラーを設けることが推奨されます。

api/v1/inventory_controller.rb は、/api/v1/inventory に対応。

api/v1/users_controller.rb は、/api/v1/users に対応。

これにより、APIの設計が標準的で再利用しやすいものになります。

まとめ: なぜ api/v1 フォルダを作成するのか？

将来の変更や機能追加に備えるためのバージョニング管理
コードの整理と可読性を向上させるため
エンドポイント構造との一貫性を保つため
RESTful設計に基づいた標準的なAPIを実現するため
このような理由から、api/v1 フォルダを作成して、その中にコントローラーを配置するのが良い設計とされています。エンドポイントの実装やテストを行う際にも、これが基本になります。