Help us understand the problem. What is going on with this article?

はじめてのRails API

More than 1 year has passed since last update.

※ 当方、はじめての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の書き方やドキュメントの作成方法には、ほかにもいくつか種類がありますので、興味のある方は調べてみて下さい。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away