クエリのような API に入門する:初めてのGraphQL

初めてのGraphQL ― Webサービスを作って学ぶ新世代API

  • Eve Porcello (著), Alex Banks (著), 尾崎 沙耶 (翻訳), あんどうやすし (翻訳)
  • 発売日: 2019/11/13


殆どのシステム開発においては何らかの API(Application Programming Interface)を使ったシステム連携が行われていると思います。

API には様々な形態と選択肢がありますが、最近は GraphQL をよく目にします。

そんな GraphQL に入門してみたい、と思ったときに非常に良い本だと思いますのでご紹介します。

ところで、GraphQL という単語は「Graph」と「QL」に分解できます。

ここでいう「Graph」は棒グラフや円グラフではなく「グラフ理論」にもとづくデータ構造(データモデル)、「QL」は「Query Language(問い合わせ言語)」が意図されていると思います。このためグラフデータへの問い合わせ言語のように思われるかもしれません。何だか難しそうな印象です。

しかし、実際に GraphQL を利用する上では学問的なグラフ理論を知っている必要はありませんし、グラフ構造に特化した問い合わせ言語でもありません。

むしろ、私には既存の API が抱えるいくつかの問題点を解決するために、新しい視点を加えた API 技術のように思えます。(そこが重要だと思ってます。)

具体的には、グラフ云々よりも、やり取りする JSON データの項目に柔軟性を持たせられる(クライアント側が必要な項目を選択できる)とか、モデルをより明確化できるなどです。

当然 GraphQL も『銀の弾』ではないと思いますが、それでも個人的には従来より一歩踏み込んだ面白い技術だと思っています。

さて、GraphQL に取り組む際の問題としてよく言われるのが「GraphQL の学習には時間がかかる」です。実際にそうかもしれません。

しかし、この本の素晴らしいところの一つは、比較的薄い本にもかかわらず、仕様だけでなく、クライアント側とサーバ側の実装をコードを通して全体像を丁寧に説明してくれており、GraphQL の敷居を下げてくれる本だと思います。

<本の内容>

【目次】
  • 1章 GraphQLへようこそ
    • 1.1 GraphQLとは
    • 1.2 GraphQLの誕生
    • 1.3 データ通信の歴史
    • 1.4 RESTの課題
    • 1.5 GraphQLの実情
  • 2章 グラフ理論
    • 2.1 グラフ理論の用語
    • 2.2 グラフ理論の歴史
    • 2.3 木というグラフ
    • 2.4 実世界でのグラフ
  • 3章 GraphQLの問い合わせ言語
    • 3.1 GraphQL APIの便利なツール
    • 3.2 GraphQLのクエリ
    • 3.3 ミューテーション
    • 3.4 サブスクリプション
    • 3.5 イントロスペクション
    • 3.6 抽象構文木
  • 4章 スキーマの設計
    • 4.1 型定義
    • 4.2 コネクションとリスト
    • 4.3 引数
    • 4.4 ミューテーション
    • 4.5 入力型
    • 4.6 返却型
    • 4.7 サブスクリプション
    • 4.8 スキーマのドキュメント化
  • 5章 GraphQLサーバーの実装
    • 5.1 プロジェクトのセットアップ
    • 5.2 リゾルバ
    • 5.3 apollo-server-express
    • 5.4 コンテキスト
    • 5.5 GitHub認可
    • 5.6 まとめ
  • 6章 GraphQLクライアントの実装
    • 6.1 GraphQL APIの利用
    • 6.2 Apollo Client
    • 6.3 Apollo ClientとReact
    • 6.4 認可
    • 6.5 キャッシュ
  • 7章 GraphQLの実戦投入にあたって
    • 7.1 サブスクリプション
    • 7.2 ファイルアップロード
    • 7.3 セキュリティ
    • 7.4 次の段階にすすむ
  • 付録A Relay各仕様解説
    • A.1 Global Object Identification
    • A.2 Cursor Connections
    • A.3 Input Object Mutations
    • A.4 Mutations updater

1 ~ 4 章までは GraphQL に関する基礎知識といった内容で、5 章以降は、サーバ側にはApollo Server、クライアント側には Apollo Client と React を使った実装の解説になっています。(Apollo Server、Client はともにオープンソースです。)

React と GraphQL といえば、Facebook のオープンソースである Relay も有名ですが、こちらには殆ど言及はありません。ただし、付録に Relay に関する追加仕様について少し言及されています。

<感想>

かなり前から「GraphQL」という言葉を何度か目にしましたが、恥ずかしながら、私が「GraphQL」が API だと知ったのはごく最近です(涙)。

かなり前に GraphQL という言葉を目にしたときは、「可視化」が流行り始めていたのでグラフの描画関係のライブラリかな?、とか、新しいグラフデータベースのクエリ言語かな?、という程度に思っていました。

当時は可視化に殆ど興味が無かったし、グラフデータベース系の技術でいえば、RDF / OWL が私の興味の中心だったこともあって、ほぼスルーしてました。

しかし、あるきっかけ(GRANDstack 関係)で GraphQL は API だと知って少し調べてみると、今まで API を設計や実装する時にくすぶっていた不満?への解決になりそうなアプローチを持っており、とても共感し、もっと知りたくなってネットで調べ始めました。

ネットで GraphQL の仕様レベルの情報を見ると、何だか理念的で理解に時間がかかりそうな気がしました。また少し緩めの情報はクライアント側中心の説明が多くて、全体像やサーバ側の実装をどのように行うか、などなど疑問が逆に噴出してしまいました。

そんな中、この本を手に取って読んでみると、非常に読みやすく、クライアント側からサーバ側まで実装を含めた全体像をざっと知ることができました(私の場合は約1日くらい)。

この本を読んだ後は、仕様レベルのドキュメントも読みやすくなりました。

そして現実の業務システムへの適用を考えはじめると、逆に様々な疑問も噴出しました。

それは GraphQL が難しいという意味ではなく、GraphQL は API なので、例えば、現実のデータモデルは RDB、NoSQL、ファイルなどなど様々にあり、これらを効率よく統合していくにはどのようにすればよいか、などという一歩進んだ疑問です。

このあたりは入門の域を超えるため、この本に期待するものではありませんが、次のステップに進むための基礎知識を短期間で得ることができたのは、この本の凄いところだと思います。

さて、ここからは本の内容から少し話はそれますが、GraphQL に関する今の時点での私の印象をメモしておきます。(今後 GraphQL に関する自分の印象がどのように変わるかの個人的な記録用です。)

システム開発に長年携わっていると、通信方式の変遷を経験して面白いです。

具体的にはインターネット時代より前の DCE、CORBA、COM / DCOM 、そしてインターネット時代になって SOAP、REST系、OpenAPI などです。(データ形式の面から見れば、効率重視のバイナリデータから、XML、JSON などのテキストベースへの流れとも言えます。)

昔の RPC 技術は IDL で厳密にプロトコルを定義するスタイルという印象ですが(バイナリ形式だから当然かな)、Web 2.0 といわれたころから JSON を中心とした厳密な型定義を行わず、緩く使える REST 系のAPIが多くなりました。

Web で広く公開される API はシンプルな仕様が多いため、この流れは気に入っていましたが、一方で業務システムレベルになると、データや機能の連続性や複雑性を扱う必要などから、やはり厳密な定義がないと厳しいと実感してました。

昔の RPC 技術に慣れた私にとっては、緩い REST 系より、近年では gRPC / Protocol Buffers あたりが好みですが、しかしブラウザからのアクセスに難があります。

一方、OpenAPI の仕様やツールも素晴らしいとは思いつつも、JSON 通信のシンプルさを殺しているような気がして、(超個人的な意見ですが)あまり好きではありません。

それに対して GraphQL のスキーマ定義とクエリ言語の仕様は、Protocol Buffers より緩い IDL を書いて、その範囲内でクライアント側に自由度を持たせられる柔軟性を感じたので、API 仕様としては従来技術のいいとこどり、といった印象を受けました。

もう一つ、GraphQL という言葉からグラフデータを扱うものと思ってましたが、API 仕様としてはグラフはあまり関係がないように思えました。

データベース的なグラフモデルには、RDF / OWL などのモデルや、Neo4j のプロパティグラフなど様々ありますが、GraphQL は具体的なグラフモデルを特定していません。(そういったグラフデータのクエリには GraphQL の定義では足りないとも言えます。)

むしろ、GraphQL のタイプ定義は JSON の型を定義しているだけのように見えます。そして、クエリは JSON の型定義に対してパターンマッチングする仕様に思えます。(その意味で、私は GraphQL というより JsonQL という印象です(笑))

これは欠点ではなく、実用的な API の仕様としてはそこが魅力だと思います。

そもそも、内部の詳細なデータ構造を隠蔽して抽象的なモデルでインターフェースを構成したほうがシステム全体としては安定したモデルになるし、適応範囲も広いと考えると、グラフモデルに特化しないことがよいと思います。

GraphQL はもともと Facebook で開発された経緯を考えると、SNS 関係のデータ表現(グラフ構造)の例が多いという事もあるかもしれませんし、従来との違いを際立たせるためにグラフを持ち出すということかもしれませんし、コンセプトの根底にはグラフ構造があるのは間違いないと思いますが、グラフを強調しすぎると(私のように)無意味な敷居を作ってしまいそうな気がします。

GraphQL の学習曲線が問題になるのは、GraphQL の仕様そのものというより、GraphQL をどのように使うか?のところにあるように思えます。

しかし、それは既存の技術でも抱える問題と同じであることが多く、それなら学習曲線が問題になる GraphQL を使う必要があるのか?となります。

これに対して Apollo の Federation とか、BFF(Backend for Frontend)といったもう少し上のレイヤから考えるアプローチや、Relay などの UI 側の実装技術を向上させるアプローチなど、GraphQL のエコシステム的な広がりがあり、今後が楽しみです。

しかし、GraphQL は、API を単なる処理とデータの定義から、よりモデル的なところに一歩踏み込んでいる気がしており、私はここに将来性を感じています。

また、Facebook の React、Relay、GraphQL に関する技術ドキュメントなどを読むと、「自分たちはこういう問題を抱えていて、その問題に対して、こうやって解決していく」という意思やストーリーを感じますし、規格のための規格ではなく、現場の問題に真摯に向き合っている気がして、とても期待しています。

最後に、このような内容をダラダラ書けたのも、今回取り上げた本が GraphQL への敷居をぐっと下げてくれたおかげと思っております。

関連記事

コメント

このブログの人気の投稿

VirtualBoxのスナップショット機能

Google Document AIで画像から表形式データを抽出する(Vision API OCRとの違い)

Ubuntu/Colab環境でPDFファイルのページを画像化する(pdf2image、pdftoppm、pdftocairo)