料理動画事業室の @yoshioriです。前に「RESTful Web API 開発をささえる Garage」で紹介した RESTful Web API を開発する Garage のクライアント側のライブラリを公開しました。この記事ではその使い方を紹介したいと思います。Garage の設計思想やサーバ側の実装については上記記事を御覧ください。

今回は簡単にクライアント側の挙動を知っていただくために pry を使って説明したいと思います。 アクセスするサーバは先程の記事で作成したアプリケーションを使用してみます。

サーバの準備

https://github.com/taiki45/garage-exampleの README にも書いてありますので簡単に進めたいと思います。

まずは下準備としてコードを github から clone してきて、ライブラリのインストールと DB のマイグレーションを行います

> git clone git@github.com:taiki45/garage-example.git
> cd  garage-example
> bundle install
> bundle exec rake db:create db:migrate

ここまででサーバの準備が整いました。次にユーザーを一人作り、アプリケーションを起動してみます

> bundle exec rails runner 'User.create(name: "alice", email: "alice@example.com")'
> bundle exec rails s

実際にブラウザで http://localhost:3000/oauth/applicationsにアクセスするとアプリケーションの登録画面が開きますのでサンプルアプリケーションひとつ作ってみます。

ここで表示された Application Idと Secretを使い下記コマンドを実行します。 （下記の $APPLICTION_IDと $SECRETをそれぞれ Application Idと Secretに書き換えて実行して下さい）

> curl -u "$APPLICTION_ID:$SECRET" -XPOST http://localhost:3000/oauth/token -d 'grant_type=password&username=alice@example.com' 

そうすると下記のように access_tokenが手に入ると思います。 今回はこれを利用します。

{"access_token":"975430489343f3d468d69f68763b3cb11d7cf98ee1f504aa319ab031a47462eb","token_type":"bearer","expires_in":7200,"scope":"public"}

GarageClient の基本的使い方

gem として公開していますので、gem コマンドでインストール出来ます

> gem install garage_client

インストールが終わったら pry を起動しライブラリをロードします。

[1] pry(main)> require"garage_client"
=> true

次にクライアントの初期設定を行います。 今回は endpoint のみを指定します。その他のオプションに関しては READMEに纏めてありますのでそちらを御覧ください。

[2] pry(main)> GarageClient.configure do |c|
[2] pry(main)*   c.endpoint = "http://localhost:3000"  
[2] pry(main)* end  
=> "http://localhost:3000"

次に先ほど取得した access_token を利用して client を作成します

[3] pry(main)> client = GarageClient::Client.new(access_token: "975430489343f3d468d69f68763b3cb11d7cf98ee1f504aa319ab031a47462eb")
=> #<GarageClient::Client:0x007f8e7ba20cb8 @options={:access_token=>"975430489343f3d468d69f68763b3cb11d7cf98ee1f504aa319ab031a47462eb"}>

では、Garage の記事で行っていたユーザーリソースを取得するリクエストを GarageClient で行ってみます。

[4] pry(main)> users = client.get("/users")
//省略
[5] pry(main)> users.first.name
=> "alice"
[6] pry(main)> users.first.email
=> "alice@example.com"

取得出来ましたね。 上記のように GarageClient で取得した値はプロパティアクセスの様に（実際にはメソッド呼び出しですが）呼び出せます。

get 以外のメソッド

次に get 以外の動作を見ていきます。garage-example は記事を投稿できるようになっているので、それを使ってみます。

[7] pry(main)> client.post("/posts", title: "sushi", body: "naoya")

投稿できました。実際に見てみましょう。

[8] pry(main)> post = client.get("/posts").first
//省略
[9] pry(main)> post.title
=> "sushi"

ちゃんと作られていますね。

では次に更新をしてみましょう。

[10] pry(main)> client.put("/posts/#{post.id}", title: "niku")
//省略

実際に更新されたかの確認を行いますが、今度は garage の link機能を使って見てみます。 GarageClient はリソースに link が指定してあると link 先のリソースを取得するときにリクエストを投げて取得してくれます。

[11] pry(main)> user = client.get("/users").first
//省略
[12] pry(main)> posts = user.posts
//ここで posts 取得のためにリクエストを投げています
[13] pry(main)> posts.first.title
=> "niku"

ちゃんと更新されているのが確認できました。 では、削除をしてみましょう。

[14] pry(main)> client.delete("/posts/#{post.id}")
//省略
[15] pry(main)> client.get("/posts").size
=> 0

ちゃんと消えましたね。 では次にもうちょっと応用的な使い方を見てみようと思います。

取得する値を絞る

Garage にはリソース取得時に必要な値だけ指定して所得する機能があります。 これは例えばレシピのタイトルだけ取得したい時などに材料や手順まで取得してしまうと効率が悪い時に値を絞ったり、逆にレシピに付いている動画情報を取得するなど標準では付加されない情報を取得したりする時に使います。

[16] pry(main)> users = client.get("/users", fields: "id,name")
//省略
[17] pry(main)> users.first.name
=> "alice"
[18] pry(main)> users.first.email //取得していないのでエラーになる
NoMethodError: undefined method `email' for #<GarageClient::Resource:0x007f8e7e03bbc8>from /usr/local/opt/rbenv/versions/2.1.5/lib/ruby/gems/2.2.0/gems/garage_client-2.1.1/lib/garage_client/resource.rb:51:in `method_missing'

キャッシュを利用する

取得する値を絞るだけでなく、取得した値をキャッシュさせることも出来ます。 動作確認様に下記に簡単な Cacher クラスを書いてみました。（実際には READMEにあるように Rails.cache を使うなどの形になると思います）

classMyCacher< GarageClient::Cachers::Baseprivatedefread_from_cache?trueenddefwritten_to_cache?
    read_from_cache?
  enddefkey"test"enddefstore@@store ||= MyStore.new
  endclassMyStoredefread(key, options)
      store[key]
    enddefwrite(key, response, options)
      store[key] = response
    enddefstore@store ||= {}
    endendend

上記をコピーし、pry コンソール上にペーストして下さい。 次に、クライアントを作るときに Cacher を指定して作ります。

[20] pry(main)> client = GarageClient::Client.new(access_token: "e32234b3d113b97d1fd38f3233c663cad67ceb4cb57e8e0a66bec00d6742b1ec", cacher: MyCacher)

実際にアクセスするときにサーバ側のログを一緒に見て下さい。

[21] pry(main)> client.get("/users")
//省略
[22] pry(main)> client.get("/users") //こっちはキャッシュから取得するのでサーバにリクエストが飛ばない
//省略

このように簡単にキャッシュ機構を組み込むことが出来ます。

簡単ですが GarageClient をつかって Garage と連携する方法を説明してみました。

また、今回は認証周りは本筋と外れるため省略しています。実際に Garage の Doorkeeper と連携する時は OAuth2 のライブラリを使用したりすると思います。 クックパッドでは Garage の記事にも出てきましたが、認証認可サーバーを別途立てていたり、内部 API として連携するときは認証を省いて使ったりしています。

社内でも実際に運用しているライブラリなので先ほど紹介した取得する値を絞る機能やキャッシュ機構など実用的なライブラリになっていると思います。 また、 今後 iOS, Android の client ライブラリも準備が整い次第公開していこうと思っています。 ご期待ください。