grapeを活用したapi設計

ruby on rails を活用してapiサーバーを作成した際の忘備録
grapeについてはgithubの情報が一番詳しいと思います。

ruby-grape/grape · GitHub

目的

• rails と grape を使用してAPIを設計する
• apiを１つ作る
• apiはバージョン管理したい

構成

1. appディレクトリ以下にディレクトリapiを作成
2. apiディレクトリ以下にディレクトリv1を作成

構成としては
v1のapiは全てroot.rbに集約する。
endpoint.rbは各バージョン（今回だとv1ディレクトリ以下）のroot.rbファイルを集約する。
検索用のapiを１つ作成する。
今後、apiをアップデートした場合はディレクトリv2を作成することでapiのバージョンが管理できます。

中身

それぞれのファイルの中身

Endpoint.rb

全apiを管理する

module Endpoint
  class API < Grape::API
    # APIアクセスに接頭辞を付加
    # ex) http://localhost:3000/api
    prefix "api"
    # 出力フォーマットをjsonにする
    format :json

    mount Root::V1
  end
end

api/v1/root.rb

バージョン情報とバージョン配下のapiを管理する

module Root
  class V1 < Grape::API
    # ex) http://localhost:3000/api/v1
    version 'v1', :using => :path

    mount Search::V1
  end
end

api/v1/search.rb

apiの動作を記述する
今回はSeriesというDBテーブルがあってそこから検索するという想定で作っています。

module Search
  class V1 < Grape::API
    # ex) http://localhost:3000/api/v1/search
    resource "search" do

      # apiの説明
      desc "return a series"

      # URLにパラメータを付加しない場合の記述
      # この例ではシリーズを全件返す
      get do
        Series.all
      end

      # apiの説明
      desc "return a series"

      # 引数の型を指定する
      # URLの指定の部分を string型で取得する
      params do
        requires :search_word, type: String
      end

      # :search_word で引数を取るようにする
      # http://localhost:3000/api/v1/search/kensaku_mozi
      # でアクセスすると 
      # params[:search_word] == kensaku_mozi
      # となる
      get ':search_word' do
        Series.find(params[:search_word])
      end
    end
  end
end

ここまで記述できれば最後に config/routes.rb に作成した api を mount してアクセスできるようになる

config/routes.rb

Rails.application.routes.draw do
  mount Endpoint::API => "/"
end

確認

rails server
で起動して
http://localhost:3000/api/v1/search
にアクセスすれば、jsonが取得できるようになる。