GraphQL

GraphQL

開発元	Facebookとコミュニティ
初版	2015年 (2015)
最新版	2018年6月
リポジトリ	github.com/graphql/graphql-spec
プログラミング 言語	Java、JavaScript、Ruby、Scalaなど
対応OS	クロスプラットフォーム
ライセンス	3条項BSDライセンス
公式サイト	graphql.org

GraphQL（グラフQL）はAPI向けに作られたクエリ言語およびランタイムである。

ウェブAPIの開発に、RESTやその他のWebサービスと比較して、効率的、堅牢、フレキシブルなアプローチを提供する。GraphQLでは、クライアントが必要なデータの構造を定義することができ、サーバーからは定義したのと同じ構造のデータが返される。したがって、必要以上に大きなデータが返されるのを防ぐことができる。ただし、これはクエリ結果のウェブキャッシュの効果に影響を与える。また、柔軟性と豊かな表現が可能なクエリ言語は複雑さを加えるため、シンプルなAPIには適さない可能性もある。GraphQLは、型システム、クエリ言語、実行セマンティクス、静的な検証、型イントロスペクションから構成される。

GraphQLは、読み込み、書き込み（ミューテーション）、データのサブスクリプション（リアルタイム更新機能で、一般にはWebHooksで実装される）をサポートする。

概要

GraphQLでは、クライアントがクエリ内容を記したdocumentを送信し、GraphQLサービスがクエリを実行し結果を返信する。documentはDSLであるGraphQL query languageを用いて記述される。以下の例は明日の天気を取得するクエリのdocumentとGraphQLサービスから返されたクエリ結果のJSONである。

// document
{
  tomorrow {
    weather
    rainyPercent
  }
}

// response JSON
{
  "tomorrow": {
    "weather": "cloudy",
    "rainyPercent": 30
  }
}

リソースをURLパスで表現するRESTful APIと異なり、GraphQLはリソースをdocumentで表現する。GraphQL WebAPIの場合、単一のAPIエンドポイントへこのdocumentをPOSTする（例:https://API.internal./graphqlエンドポイントへdocumentをBodyとしてPOSTする）ことでクエリが実行される（参考: アプリケーションプログラミングインタフェース#様式 ）。

GraphQLはあくまでAPI仕様であり、通信方式の実装とは独立している。例えばGraphQL WebAPIを実装する際、documentをURLクエリ文字列に載せることも可能である（例:GET https://API.internal./graphql?query={tomorrow{weather}}）。

機能

Arguments

GraphQLではargumentを用いたクエリの制御が可能である。GraphQLオブジェクトの各field（例: tomorrow）は0個以上のargumentsを持てる。GraphQLサービスではクエリをトップレベルのfieldからresolverによって解決していくが、argumentsはその時にresolverへ渡されresolverの振る舞いを制御する。次の例では"都道府県名/name" argumentと"天気/weather" argumentを用い、都道府県-街リストから東京/tokyoに含まれる晴れ/sunnyの街を取得する。

// document
{
  prefecture(name: "Tokyo") {
    prefName
    cities(weather: "sunny") {
      cityName
      rainyPercent
}}}

// response JSON
{
  "prefecture": {
    {
      "prefName": "Tokyo",
      "cities": [
        {
          "cityName": "Shinjuku",
          "rainyPercent": 10
        },{
          "cityName": "Ikebukuro",
          "rainyPercent": 0
}]}}}

directives

GraphQLではdirectivesを用いたクエリの制御が可能である。GraphQLオブジェクトの各field（例: tomorrow）はdirectiveを持てる。directivesは処理系に依存したあらゆる処理を指定するアノテーションである。全ての処理系に実装されるdirectiveの例としてfieldの無視を指定する@include(if: Boolean)がある。

// document
{
  sinjuku {
    weather
  }
  ikebukuro @include(if: false) {
    weather
    rainyPercent
}}

// response JSON
{
  "sinjuku": {
    "weather": "cloudy"
}}

全てのresolverに@include相当の引数を用意すれば同等の機能を提供できるが、directivesを用いることでresolverに手を加えずかつdirective処理系1箇所での実装のみでこの機能を提供できる。

directivesはGraphQLサービス処理系以外にも利用されうる。例えばAWS AmplifyはSchema上のdirectivesに基づいたクラウドリソースプロビジョニングコード生成（"GraphQL Transform"）を実装している。@modelが付与されたfieldはresolverが自動で生成されかつDynamoDBにリソースが準備される。これはGraphQLサービス処理系ではなく、Amplify CLIによっておこなわれる。

形式

Document

Documentは1つ以上のOperationDefinitionからなる。1つのみの場合Nameが省略可能であり、さらにOperationTypeがqueryならこれも省略できる。

// document
OpType Name [VarDef][Directives] {
  ...
}
OpType Name [VarDef][Directives] {
  ...
}
// e.g.
query ExampleQuery1 {
  resource
}
query ExampleQuery2 ($var: S) @skip(if: false) {
  time
}

Field

FieldはNameからなっており、Alias, Arguments, Directivesを利用できる。さらにサブFieldを持つことができる。

// document
{
  [Alias] Name [Arguments][Directives] [SelectionSet]
}
// e.g.1 - simple
{
  resource
}
// e.g.2 - full
{
  time: resource (arg1: "arg") @skip(if:false) {
    subResource
  }
}

歴史

GraphQLは、2012年にFacebookの内部で開発され、2015年に公開された。2018年11月7日、GraphQLプロジェクトは、Facebookから非営利のLinux Foundationがホストする新たに設立されたGraphQL Foundationに移譲された。2012年以来、GraphQLの利用数は、GraphQLの作者のLee Byronが想定したとおりのスケジュールに正確に従って増加している 。Byronの目標は、GraphQLをWebプラットフォーム全体で利用されるようにすることである。

2018年2月9日、GraphQL Schema Definition Language（SDL）が仕様の一部となった。

実装

主要なGraphQLのクライアント実装としては、Apollo ClientとRelayがある。GraphQLサーバーは複数の言語で利用可能であり、Haskell、JavaScript、Perl、Python、Ruby、Java、C#、Scala、Go、Elixir、Erlang、PHP、R、Clojureで書かれたものがある。

関連項目

• Query by Example
• OpenAPI Specification

外部リンク

• 公式ウェブサイト