GraphQLはRESTの置き換えではない

GraphQLは最近注目されているWeb APIのための問い合わせ言語だ。
現在主流のRESTfulなAPIはURLとmethodでリソースを表現するわけだが、GraphQLは単一エンドポイント（ex: "POST /graphql"）だけ存在し、欲しいリソースをHTTP POSTのbodyに明示的に記載してリクエストする。

↑JSON APIをGraphQLの形式でコールする（引用: how to graphql )

徐々に実装例が増えてきており、2016年にはGithubがAPIの実装を全面的にGraphQLに移行させたのが注目された。

GitHub GraphQL API v4 | GitHub Developer Guide

色々調べていくと、GraphQLは単にRESTの代替ではなく、開発・運用フローを一新させうるほど豊かな思想・機能を含む事が分かって来たので現状の整理をしてみたい。

APIリクエストを束ねて効率化

RESTではURLがひとつのリソースを表すため、複数のリソースが必要な複雑な画面では複数回のAPIリクエストが必要になる。結果的に、綺麗に設計されたRESTful APIほど複数回のリクエストが必要になり、パフォーマンスが落ちたりコードの複雑さが増す欠点があった。

GraphQLでは必要なリソースだけを明示的に記載してリクエストし、必要なリソースを無駄なく1発で取得可能だ。

GraphQLではフィールドの一部分だけが欲しい（ex: userのnicknameだけが欲しい）際は必要なフィールドだけを明示的に指定できるので、返りのJSONのサイズを抑える事ができる。これもAPIの効率化といえそう！

スキーマファースト開発

API開発者とフロントエンド開発者の間で事前にAPIのスキーマを相談して決定し、パラレルに開発することで結合時の手戻りを防ぐプロセスが最近注目されている。スキーマを元にテストやモック、ドキュメントも自動生成できて便利である。

詳しくは、OpenAPI、swagger、JSON Schemaなどでぐぐってみて欲しい

GraphQLはスキーマ定義が仕様に深く組み込まれており、必然的にスキーマファースト開発になる。現在のベストプラクティスに自動的に乗っかれるのは嬉しみポイントだ。

マイクロサービスのAPI Gateway

GraphQLはマイクロサービスのGateway（中間層）としても良筋と思われる。GraphQLサーバはスキーマ定義に対応するデータを複数のデータソースから引っ張るわけだが、直接DBを叩いてもいいし、既存のRESTful APIを内部的に叩いてもOKである。以下の図がわかりやすい。

リソース制限の視点

サーバー負荷を抑える観点から、APIに利用制限が設定される事がある。RESTでは1時間にx回マデなどの回数ベースの制限を設ける例がよくあるが、GraphQLは引っ張るリソース数(=負荷)はクライアントが任意に決められるため、負荷の計算方法を考える必要がある。githubのGraphQL API v4は、なめるオブジェクトの数をscoreにし、それを1時間に超えない範囲でリクエスト可能にしている。

GraphQL resource limitations | GitHub Developer Guide

キャッシュ効率

GraphQLは単一エンドポイントなので、HTTPのCache-ControllのようなURLベースのキャッシュ機構やCDNでのキャッシュはそのままでは使えない。もちろん、キャッシュが使えないわけではなくサーバー、CDN、クライアントの各層でキャッシングの現実的な実装が用意されている。詳しくは、下記リンクの議論を参照してみてほしい。

GraphQL vs REST: Caching

Caching GraphQL results in your CDN – Apollo GraphQL

Caching data | Apollo Client

エラーハンドリング

RESTではエラーはHTTPのステータスコードで表現されるが、GraphQLではリクエストが通れば200で返し、何かエラーが発生した時はエラーオブジェクトに内容が吐かれる。RESTから移行する際はクライアントでのエラーハンドリングも修正が必要となるだろう。

モニタリング

GraphQLは単一のエンドポイントなので、エンドポイントごとにレスポンス性能を監視することはできない。Newrelicでの対応例を以下に挙げたが、なんらかの工夫が必要になってくる。

GraphQL Performance Monitoring with New Relic – EatCodePlay

学習コスト

GraphQLは広く普及しているRESTとは思想が違い、事例も少なく、技術的にも枯れてもいないため、学習コストはそれなりに高いと感じる。

まず、"使う" 方として、githubのAPI v4が肌感を掴むのによさそうだ。GraphQLをExploreで叩いてクエリの組み方やObject、Interface、Mutationなどの登場人物を覚え、そのあとにApolloなどのフレームワークを用いてGraphQLサーバーを立てるのが素直か。

まとめ

GraphQLはRESTの代わりとしてWebAPIの層を置き換えるのではなく、開発フローや運用自体を次のフェーズに進める可能性を秘めた技術になり得そうだ。まだ枯れていないので動向を注視いただければと思う。

[追記]

BitJourneyのgfx氏がkibelaのGraphQLコーディングガイドを公開しています
https://bitjourney.kibe.la/shared/entries/1f26acbe-315f-42b8-9ecd-11bcaac5b697