RailsのAPIのバージョンについて
自分が参画した開発現場では一からサービスを作成しておらず、すでにリリースしているサービスの改修をしていました。その中でAPIの機能を使用して実装していたのでメモを残します。
RailsのAPIとは？
API専用アプリケーションを支援するRailsの機能のことであり
近年、さまざまなクライアント側フレームワークが登場したことによって、Railsで構築したバックエンドサーバ―を他のWebアプリケーションとネイティブアプリケーションの間で共有する手法が増えてきました。
たとえば、Twitterは自社のWebアプリケーションで パブリックAPI を利用しています。このWebアプリケーションは、JSONリソースを消費するだけの静的サイトとして構築されています。
多くの開発者が、Railsで生成したHTMLフォームやリンクをサーバー間のやりとりに使うのではなく、Webアプリケーションを単なるAPIクライアントにとどめて、JSON APIを利用するHTMLとJavaScriptの提供に専念するようになってきました。
コントローラー作成に関する以下のコマンドを実行しましょう。
rails g controller v1::todos
コントローラーを作成していますが、v1::todosという見慣れない書き方をしています。
vはバージョンを表す英単語で、数字はそのバージョンを示しています。
こちらの書き方でコントローラーの作成を実行すると、ご覧の通りv1というディレクトリの中にコントローラーを作成してくれます。
また、作成されたコントローラーのファイルも確認してみてください。
api/app/controllers/v1/todos_controller.rb
class V1::TodosController < ApplicationController
end
バージョンを指定してコントローラーを作成した理由
上では、v1というバージョンを指定してコントローラーを作成しました。
本段落では、その理由を説明します。
そもそもAPIは機能の追加や変更、更には廃止といった多くの修正を開発現場ではしていきます。
一度公開したAPIはできるかぎり変更しない方がユーザーにとって良いですが、なかなかそれは難しいです。
そのような状況下でAPIの修正を行っていくためには、前からサービスを使用しているユーザーにも、新しく使用するユーザーにも対応できるAPIを作成していかなければなりません。
つまり、複数のバージョンのAPIを同時に提供する可能性があるということです。
具体的に言うと、リリースしているサービスに影響が出ないようにバージョン1のAPIのある部分を残したままバージョン2で新機能を追加してバージョン1に影響が出ないようにするといった感じです。
コントローラーの書き方
以下コントローラーは、
TODOのデータ全てをJSONの形式でユーザーに返すアクションです。これでjson形式のAPIが出来ています。
サンプル
def index
todo = Todo.all
render json: todo
end
以下のサンプルコードの意味はv1のバージョンでTODOのデータ全てをJSONの形式でユーザーに返すindexアクションです。
class V1::TodosController < ApplicationController
def index
todo = Todo.all
render json: todo
end
end
このようにバージョンを分けられるようにしておけば、古い形式でアクセスしてきているユーザーに対してはバージョン1のAPIでデータを渡したり、新しいユーザーにはバージョン2のAPIでデータを渡したりといったことが可能になります。
ルーティングの作成
サンプル
Rails.application.routes.draw do
# For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
namespace :v1 do
resources :todos, only: [:index, :create, :destroy]
end
end
まずは、namespaceの部分から。前の節では、APIのバージョンを分けることに関して、以下のような説明をしておりました。
このようにバージョンを分けられるようにしておけば、古い形式でアクセスしてきているユーザーに対してはバージョン1のAPIでデータを渡したり、新しいユーザーにはバージョン2のAPIでデータを渡したりといったことが可能になります。
つまり、ルーティングでも、バージョンの変更がしやすい実装を心がける必要があります。
Railsのルーティングではnamespaceという機能を使うことができ、こちらを使うとURLのHelperとPathに指定した文字がつきます。