GraphQLってどうだろう。

APIサーバー

JSON API サーバーを開発するとき、クライアントはHTTPリクエストを発信し、サーバーは応答をJSON表現のデータ構造で返す。

このようなAPIの設計について、従来はRESTがよいとされてきた。
facebookが提案するGraphQLというものが、Github API v4 に採用されるなど実績がつまれてきたので調べてみた。

REST api おさらい

Ruby on railsのリソース表現にも採用され、こうした特長がある。

• RESTの原則

  • (Uniform Interface) 情報の操作は、すべてHTTPメソッド(GET, POST, PUT, DELETE)でおこなう。
  • (Addressability) リクエストのＵＲＬによって、提供する情報がひとつに定まる。
  • (Stateless) サーバーは状態をもたない。
  • (Connectability) 応答する情報に、別の情報へのリンクを含めることができる。

• RESTの性質

  • GETリクエストは再実行に対して安全である。
  • PUT等のリクエストは再実行しても指示以上の動作をおこさない（べき等と呼ぶ）
  • サーバーはリソースごとに固有のURLをもち、メソッドによって操作が決まる。

• RESTの実際

  • とはいえ、必要な情報をかき集めるためには、普通はindexなどのREST外URLも使うよ。

GraphQL api

GraphQL では、応答のデータ構造はリクエストが決定する。
RESTが取り組んできたUniform Interface、Addressability、については修正される。

• GraphQLの原則

  • あらゆるGraphQLのリクエストと、応答を引き受ける、唯一のURLを提供する。
  • 仕様化されたクエリ言語で情報を請求したり、操作を請求したりする。

• GraphQLの性質

  • 個々のリクエストにあわせて通信内容を絞り込むので、最小限の通信サイズとなる。
  • 必要な多数のリソースを、関連づいた形式でまとめて取得する。
  • 書き込み系処理の仕様変更をサーバーで吸収しやすい。

GraphQL ⇔ REST

REST、GraphQL でアクセスするAPI サーバーを想像してみた。

※ graphql-ruby で構築した場合

このとき、開発者は下表のような量のコードを記述する。（graphql-ruby IDLが採用されると、記述はシンプルになりそう。）

	単位	GraphQL	REST
config/routes.rb	行	1	3
app/controllers/*	action	1	5 * 3 + 1 = 16
app/models/*	class	3	3
app/graphql/*	schema	1	0
app/graphql/types/*	type	5	0
n+1 対策 (lazy)	class	2	0

RESTでは、同コントローラークラスのactionに処理を記述する。共通部分は private method にまとめるか、 modelに追い出すリファクタリングをしていく。
比べてGraphQLでは、Fieldのresolveに処理を記述する。共通部分は主にmodelへ追い出すリファクタリングをする。
また、n+1回DB問い合わせをしてしまう問題をチューニングするため、lazy_resolve インターフェースに従うキャッシュを実装する。

GraphQL 導入方法

Ruby on Rails へ GraphQLを導入するには

gem "graphql"
gem "graphql-batch"
gem "graphiql-rails"

rails generate graphql:install --batch --schema=#{AppName}Schema
rails g graphql:function #{function_name}
rails g graphql:mutation #{mutation_name}
rails g graphql:loader

書き方

参考になるサンプル。 https://github.com/joe-re/sample-graphql-on-ruby
Schema、query type、 mutation type を構築する。
実務では、それらが持つfieldは、のtype定義は、modelごとにファイルを用意して管理するとよい。

• Schema
  • query
    • field
      • type
      • argument
      • resolve
  • mutation
    • field
      • type
      • argument
      • resolve

参考

http://graphql-ruby.org/
https://github.com/graphql/graphiql
http://mgiroux.me/2015/getting-started-with-rails-graphql-relay/