RailsでGraphQL APIをつくる: Part 1 - GraphQLとは何か（翻訳）

概要

原著者の許諾を得て翻訳・公開いたします。

• 英語記事: Building a GraphQL API in Rails - Part 1
• 原文更新日: 2016/11/22
• 著者: Wayne Chu

Part 2は来週公開いたします。

RailsでGraphQL APIをつくる: Part 1 - GraphQLとは何か（翻訳）

このブログ記事シリーズでは以下の3つのトピックについて扱います。

1. GraphQLとは何か（本記事）
2. Railsで基本的なAPIを書く
3. ベストプラクティス集

---

GraphQL自体はそこそこ前からありますが、GitHub自身がGraphQL API alphaをリリースしたのをきっかけに、GraphQLについて調べてみることにしました。GitHubは開発者になくてはならないものとなってから既に久しく、GitHubのRESTful APIは開発者にとって今やある意味で標準といえます。そのGitHubがリリースしたGitHubのGraphQLの新機能を追うのはかなり面白い作業です。

このトピックはミートアップで私が話した内容を元にしています。ご興味のある方は私のスライドやサンプルリポジトリをどうぞ。

それでは始めましょう。

1. GraphQLとは何か

最初に申し上げておくと、GraphQLを学ぶにはGraphQLを実際に動かしてみるのがベストです。ぜひGraphQLのチュートリアルでいろいろ遊んでみてください。graphql.orgが特におすすめですが、Github GraphQL APIでもいろんなことができます。いずれも遊びながらGraphQLを学ぶには絶好のリソースです。

ところで、GraphQLとは一体何でしょうか。

私が答えるより、graphql.orgの公式な定義「自分のAPIに対して使えるクエリ言語の一種」の方がよいでしょう。しかしどういう意味なのでしょうか。次の例でおわかりいただけると思います。

GraphQLクエリをAPIリクエストのパラメータとして渡すと、サーバーはクエリを実際のSQLに翻訳して実行し、求めていた値を返します。実にシンプルです。

今なぜGraphQL？

GraphQLが誕生した理由は何でしょうか。RESTful APIやRPC APIではなくGraphQLを使うメリットは何でしょうか。そこで、GraphQLのメリットを2つの立場から見てみましょう。

フロントエンド開発者にとってのGraphQL:

1. 1回のリクエストでいくつでもリソースを取得できる
2. レスポンスを自由にカスタマイズできる

先の例で見たように、フロントエンド開発者は1回のリクエストで複数のリソースを取得できます（RESTful APIだとすべてのエンドポイントがそれぞれ1つのリソースなので、リソースの数だけリクエストを送信しなければなりません）。また、レスポンス名を自由にカスタマイズできるのでモデルを無駄に改造せずに楽に開発できます。

バックエンド開発者にとってのGraphQL:

1. バージョンレス API
2. APIドキュメントが不要なIntrospectionシステム

訳注: Introspection（宗教、心理学方面で言う「内観」など）

GraphQLのベストプラクティスのひとつに、「APIのバージョンを変えないこと」というのがあります。バックエンド開発者はリソースの型（type）を定義しておけば、APIのレスポンスの詳細について何も指定する必要はありません（同僚のフロントエンド開発者は、欲しいクエリを投げるだけでどんなレスポンスが戻ってくるかを確認できます）。バックエンド開発者の作業はモデルの抽象レイヤを定義するだけで終わりますので、あとはフロントエンド開発者にすべておまかせです。

さらにうれしいことに、APIドキュメントを頑張って書く必要がありません（本当に助かります！）。リソース（型、要するにAPIモデル）を定義しておけば、たとえばswaggerやJSON-Schemaなどをself-introspection機能で確認できます。これによって、フロントエンド開発者はAPIの型リストをチェックするだけで、どんなクエリを送信すればよいかを自分で確認してからクエリを送信できるようになります。

訳注: self-introspectionは、「APIが自らAPIの仕様を答えてくれる」システムとも言えます。

理解を深めるため、ここでGraphQLとRESTとRPCを比較してみましょう。

## REST

GET  https://myblog.com/articles
GET  https://myblog.com/articles/1
POST https://myblog.com/articles?title=hello

## RPC

GET  https://myblog.com/getAllArticles
GET  https://myblog.com/getArticle?id=1
POST https://myblog.com/createArticle?title=hello

## GraphQL

GET  https://myblog.com/graphql?query=graphql_query_here
POST https://myblog.com/graphql?query=graphql_query_here

RESTの場合、1エンドポイント=1リソースとして扱いますので、エンドポイントの数だけリソースがあります。RPCの場合は関数として扱います。しかしGraphQLはあたかもqueryパラメータでSQLコマンドを渡すような感じになります（もちろん本物のSQLとは違いますが）。

実際にコードを書いてみる前に、GraphQLをどう捉えるのがよいのか改めて考えてみましょう。ここでは以下の図と文を引用するにとどめますので、後は皆さまでお考えください。

ビジネスロジックはこの図のどこで定義すべきか、バリデーションや認証チェックは図のどこで行うべきかおわかりでしょうか。その答えは「図の青いブロック: 専用のビジネスロジック層」になります。ここに置いたビジネスロジック層は、ビジネスドメインのルールを尊守するうえでの単一かつ信頼できる情報源として振る舞うべきです。
http://graphql.org/learn/thinking-in-graphs/#business-logic-layerより

理論はこのぐらいにして、すぐにもコードを書いてみましょう。「Part2 - Railsで基本的なAPIを書く」に続きます。