2020/6 GraphQLを使ってみた - 概要編

2020年6月29日に公開大阪

最近よく周りで耳にする（？）GraphQL。実際にお仕事にて使わせていただく機会がありましたので、どのようなものか、どのように利用するかを複数回に分けてお送りいたします。

GraphQLとは

そもそも、GraphQLとはどういうものなのでしょうか？公式ホームページ（https://graphql.org/）にはこのように記載されています。

※以降の翻訳はGoogle翻訳にて行い、そこからさらに私の方で意訳しております

A query language for your API GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

訳）GraphQLはAPIのクエリ言語で、既存のデータでこのクエリを実行するためのランタイム。　また、API内のデータを分かりやすく説明し、クライアントに必要な情報だけを提供する。　そして、APIを長期的かつ容易に改修することができ、強力な開発者ツールも有効にすることが出来る。

Facebook's mobile apps have been powered by GraphQL since 2012. A GraphQL spec was open sourced in 2015 and is now available in many environments and used by teams of all sizes.

訳）Facebookのモバイルアプリにて2012年から使用され、GraphQL仕様として2015年にオープンソース化された。

列挙すると下記となります。

分かりやすいAPI仕様
必要な情報のみをクライアントに提供
長期的にかつ容易に改修することが可能
強力な開発者ツールも使用可能
Facebookにて開発されて2012年からモバイルアプリで利用、2015年に世に放たれたAPI仕様

いずれも従来のAPI開発者からするととても魅力的に見えますね...。

また、上記と重複しますが、同ページにてGraphQLの特徴が簡潔に説明されています。

Ask for what you need, get exactly that

訳）必要なもののみを取得

Get many resources in a single request

訳）1つのリクエストで多くのリソースを取得する

Describe what’s possible with a type system

訳）型システムで何ができるかを説明する

その他にも記載がありますが、大きな特徴としてはこれらの3つとなります。具体的にどういうことでしょうか。それぞれの特徴について確認していきましょう。

GraphQLの特徴

以降では、具体例として下記のデータを利用いたします。

データベースのテーブル定義

テーブル内のデータ一覧

1. Ask for what you need, get exactly that

まず1つ目、必要なもののみを取得ということですが、従来のAPIでも必要なものだけ提供すれば取得できるんじゃない？と思います。ただ、GraphQLに関してはAPI側ではなくクライアント側での項目の取捨選択が可能となります。実際の取得例をみてみましょう。

GraphQL標準の開発者ツール

※左：クライアント側（リクエスト時のBody内のquery内容）　右：API側（レスポンス内容）

curlコマンドで表すと以下となります。

# 画像と同様のリクエスト
## リクエスト内容
$ curl -X POST -d '{ "query": "{ findBookById(id:1) { id title author price } }" }' -H 'Content-Type: application/json' http://localhost:8088/rdb
## レスポンス内容
{"data":{"findBookById":{"id":"1","title":"title1","author":"author1","price":100}}}

# 項目を減らしたリクエスト
## リクエスト内容
$ curl -X POST -d '{ "query": "{ findBookById(id:1) { id title } }" }' -H 'Content-Type: application/json' http://localhost:8088/rdb
## レスポンス内容
{"data":{"findBookById":{"id":"1","title":"title1"}}}

上記のように、クライアント側はリクエスト時に指定した項目のみを取得することが可能となります。 API側の実装としても、利用するクライアント毎に項目を絞る必要なく提供することが可能です。（API側の実装方法の詳細は次回以降で記載いたします）

2. Get many resources in a single request

2つ目は、1つのリクエストで多くのリソースを取得するとのことです。 REST APIですと、ひとつのURLに対して1つのリソースの操作となります。ですが、GraphQLはひとつのURLで全てのリソースの操作が可能となります。

※左：REST API　右：GraphQL

これにより、クライアントは取得するリソースへのクエリのみを考慮するだけで提供された全リソースへのアクセスが可能となります。

3. Describe what’s possible with a type system

3つ目は、型システムで何ができるかを説明する、となります。 GraphQLでは、定義情報として下記のようなスキーマが必ず必要となります。

# Bookの定義
type Book { 
    id: ID, 
    title: String, 
    author: String, 
    price: Int 
}
# 各データを取得するクエリの定義
type Query { 
    # 単一のBookを取得するクエリ定義
    findBookById(id: ID): Book
    # 全てのBookを取得するクエリ定義
    findAllBooks: [Book]
}

このスキーマだけで、このGraphQLにどのようなクエリが用意され、どのように返却されるかが読みとれます。そのため、従来のAPIのように別途仕様書を作成せずとも、このスキーマ情報をクライアント開発者に共有するだけで提供しているクエリを周知させることが可能となります。

今回は概要編として、GraphQLの公式に記載されている概要と3つの特徴についてご紹介させていただきました。次回は、このGraphQLを用いて簡単なAPIを作成していこうかと思います。

# Node.js # 入門 # 大阪

2019/7 HTTPメソッドとCRUD