※ 当方、はじめてのQiita投稿になりますので、どうかお手柔らかにお願いいたします。
そもそもAPIってなあに？
APIは、アプリケーションプログラミングインターフェースの略です。
「WebAPIについての説明」という記事の「WebAPIの一旦のまとめ」に、簡潔でとてもいい説明がありました。
- サーバーで用意している関数(機能)をhttpで通信して利用する事。
- 利用するには決め事を守ってリクエストを出す。
- 決まり事とはURLとか渡すデータの名前とかデータの形式とか。
- レスポンスは大体何かしらのデータ。時々画像も。
- データの形式は最近はJSON。一昔前はXMLが主流だった。
- ajax形式で利用される事が多い
上記の記事を最初から全部読むのは大変だと思うので、概念から知りたい、という場合は以下の記事が参考になります。
もっとコンピューターサイエンス的な観点で知りたい、という場合は、最初の記事をつまみ食いしながら読むと良さそうです。
そういうことで、APIはどうやらJSON形式のデータだということが分かりました。
JSONについて知りたい方は、以下の記事を読んでみて下さい。
JSON形式のデータは、こんな感じの見た目をしています。
{ "hoge": 1, "fuga": { "hoge": "hello" }}
このようなデータが返ってくるようなAPIを、これからRailsで作ってみたいと思います。
Rails API を作成しよう
1. Railsプロジェクトの作成
まずはAPIモードでRailsプロジェクトを作成しましょう。
APIモードでRailsプロジェクトを作成すると、APIには不要なView・UI関連のライブラリがインストールされません（Rails4まではrails-apiというgemを入れる必要がありました）。
APIモードでRailsプロジェクトを作成するには、rails newするときに、--apiオプションを付けます。
$ rails new api-project --api
2. Model、Controllerの作成
今回はscaffoldで作ってしまいましょう。
$ rails g scaffold users
できたModelは以下のようになります。
class User < ApplicationRecord
end
また、Controllerは以下です。
render json:がいっぱいありますね。これでjson形式のAPIが出来ています。
class UsersController < ApplicationController
before_action :set_user, only: [:show, :update, :destroy]
# GET /users
def index
@users = User.all
render json: @users
end
# GET /users/1
def show
render json: @user
end
# POST /users
def create
@user = User.new(user_params)
if @user.save
render json: @user, status: :created, location: @user
else
render json: @user.errors, status: :unprocessable_entity
end
end
# PATCH/PUT /users/1
def update
if @user.update(user_params)
render json: @user
else
render json: @user.errors, status: :unprocessable_entity
end
end
# DELETE /users/1
def destroy
@user.destroy
end
private
# Use callbacks to share common setup or constraints between actions.
def set_user
@user = User.find(params[:id])
end
# Only allow a trusted parameter "white list" through.
def user_params
params.fetch(:user, {})
end
end
3. jsonを確認してみよう
実際にjsonを見てみましょう。
先ほどUserモデルを作成したため、一度マイグレーションを行ってから、ローカルのRailsサーバーを立ち上げます。
$ rails db:migrate
== 20171216035325 CreateUsers: migrating ======================================
-- create_table(:users)
-> 0.0015s
== 20171216035325 CreateUsers: migrated (0.0015s) =============================
$ rails s
以下のURLにアクセスすると、
http://localhost:3000/users
真っ白な画面に[]と表示されています。
この画面はUser#indexのアクションで、User一覧のjsonが出力されるのですが、まだUserのデータがひとつも入っていないため、空の配列が表示されています。
ですので、正常に表示されているということになります。
これだけだとさみしいので、データが入った状態のjsonを確認するために、nameカラムを追加します。
マイグレーションファイルを作成して、その内容を更新し、再度マイグレーションを行います。
これでnameカラムが追加されました。
これからUserのデータを入れるためにpostを行うので、Controllerのストロングパラメータを更新します。
以上の準備ができたところで、以下のコマンドで新しいUserを作るAPIを叩いてみましょう。
$ curl -X POST http://localhost:3000/users -d 'user[name]=meru'
{"id":1,"created_at":"2017-12-16T04:30:04.202Z","updated_at":"2017-12-16T04:30:04.202Z","name":"meru"}
このようなレスポンスが返ってくれば、成功です。
それでは、先ほどのURLに再度アクセスしてみましょう。
http://localhost:3000/users
以下のように表示されていれば、成功です。
[{"id":1,"created_at":"2017-12-16T04:30:04.202Z","updated_at":"2017-12-16T04:30:04.202Z","name":"meru"}]
テストの作成
APIのテストは、エラーハンドリング（各種エラーをどのように処理するか）の検証で重要になります。
APIではない通常のRailsアプリケーションでもテストは欠かせませんが、APIを目視や動作確認で検証するなんてますます面倒ですので、APIを作る際には必ずテストを書くようにしましょう。
今回はrspecで作成したいので、これまで作成してきたRailsプロジェクトに、rspecをインストールします。
方法については、以下の記事を参考にして下さい。
APIのテストは、spec/requestsディレクトリ以下に作成します。
$ bundle exec rails generate rspec:integration User
これで、テストファイルが自動生成されます。
今回はUser#indexだけテストを行います。
テストの内容を更新し、テストを実行してみましょう。
$ bundle exec rspec
.
Finished in 0.17578 seconds (files took 1.87 seconds to load)
1 example, 0 failures
これで、APIのテストが出来ました。
API ドキュメント も忘れずに
APIからレスポンスを受けるには、渡すデータの名前やデータの形式などの決め事を守ってリクエストを出すこと、という説明が前半でありました。
API ドキュメントは、その決め事を何らかの形で見える化するものです。
リクエストを出す側の気持ちを考えると、APIを作るなら必ず残しておきたいですね。
ちなみに、QiitaのAPIドキュメントはこんな感じで、
esaのAPIドキュメントはこんな感じです。
rails guideのように$ bundle exec rake rdocで生成して、マークダウンで書いていく方法もありますが、
autodocというツールを使えば、rspecのテストから自動生成できます。
先ほど作成したテストをもとに、APIドキュメントを生成してみましょう。
Gemfileにgem 'autodoc, group: :test'を追加し、$ bundle installをします。
その後は、以下の記事を参考にしながら進めましょう。
これで、APIドキュメントが作成できました。
まとめ
後半駆け足になってしまいましたが、「RailsでAPIっていうものを作ってみたいけどやり方がわからない...」という方向けに、APIの作成からテスト、ドキュメントの作成方法までご紹介しました。
APIの書き方やドキュメントの作成方法には、ほかにもいくつか種類がありますので、興味のある方は調べてみて下さい。