GraphQLの紹介

GraphQLの用語

GitHub GraphQL APIは、GitHub REST APIからのアーキテクチャ及び概念的な移行を表すものです。 GraphQL API のリファレンスドキュメントでは、いくつかの新しい用語が登場することになるでしょう。

スキーマ

スキーマは、GraphQL APIの型システムを定義します。これは、クライアントがアクセスできる、存在しうるデータ（オブジェクト、フィールド、リレーションシップ、すべて）の完全な集合を記述します。クライアントからの呼び出しは、スキーマに対して検証され、実行されます。クライアントは、イントロスペクションを使用してスキーマに関する情報を確認できます。スキーマはGraphQL APIサーバー上にあります。詳細については、「GraphQL API の検出」を参照してください。

フィールド

フィールドは、オブジェクトから取り出せるデータの単位です。 GraphQL の公式ドキュメントでは、「GraphQL クエリ言語は、基本的にオブジェクトのフィールドを選択するものです」と記載されています。

公式仕様では、フィールドについても次のように記載されています。

すべてのGraphQLの操作は、明確な形のレスポンスが保証されるよう、スカラー値を返すフィールドまで降りた指定をしなければなりません。

これはすなわち、スカラーではないフィールドを返させようとすると、スキーマ検証でエラーが投げられるということです。すべてのフィールドがスカラー値を返すまで、入れ子になったサブフィールドを追加しなければなりません。

引数

引数は、特定のフィールドに添付されるキー/値ペアの集合です。フィールドの中には、引数を必要とするものがあります。ミューテーションでは、引数として入力オブジェクトが要求されます。

実装

GraphQL スキーマでは、実装という用語を使用して、オブジェクトがインターフェイスからどのように継承されるかを定義することがあります。

以下は、インターフェース X とオブジェクト Y を定義するスキーマの考案された例です。

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

これは、オブジェクト Y でインターフェース X と同じフィールド/引数/戻り値の型が必要とされる一方で、オブジェクト Y 固有の新たなフィールドを追加する必要があるということです。 (! はそのフィールドが必須であることを意味します。)

リファレンスドキュメントには、以下のような記述があります。

各オブジェクトには、継承元のインターフェイスが [実装] の下に一覧表示されます。
各インターフェイスには、継承 するオブジェクトが [実装] の下に一覧表示されます。

Connection

コネクションを使うと、同じ呼び出しの一部として関連するオブジェクトに対するクエリを実行できます。コネクションを使うと、REST APIでは複数の呼び出しを使うような場合に、単一のGraphQL呼び出しを使うことができます。詳細については、「REST から GraphQL への移行」を参照してください。

点を線でつなぎ、グラフを図示すると役立ちます。点はノードで、線はエッジです。コネクションは、ノード間の関係を定義します。

Edge

エッジは、ノード間のコネクションを表します。コネクションに対してクエリを行うと、そのエッジをトラバースしてノードを取得することになります。すべての edges フィールドには、node フィールドと cursor フィールドがあります。カーソルは改ページ位置の自動修正に使用されます。

Node

ノード はオブジェクトの総称です。ノードは直接ルックアップすることもできますが、コネクションを通じて関連するノードにアクセスすることもできます。スカラーを返さない node を指定する場合は、すべてのフィールドでスカラーが返されるまでサブフィールドを含める必要があります。 REST API を通じてノード ID にアクセスし、それらを GraphQL クエリで使用する方法について詳しくは、「グローバルノード ID を使用する」を参照してください。

GraphQL APIの発見

GraphQL は内省的です。これはすなわち、GraphQLスキーマに関する詳細をクエリできるということです。

__schema に対してクエリを実行して、スキーマで定義されているすべての型を一覧表示させ、それぞれの詳細を取得します。

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

__type に対してクエリを実行して、任意の型の詳細を取得します。

query {
  __type(name: "Repository") {
    name
    kind
    description
    fields {
      name
    }
  }
}

GET 要求を使用して、スキーマのイントロスペクションクエリを実行することもできます。
```
$ curl -H "Authorization: bearer TOKEN" http(s)://HOSTNAME/api/graphql
```
注: "message": "Bad credentials" または 401 Unauthorized 応答を受け取った場合は、有効なトークンを使用していることを確認してください。 GraphQL API では、personal access token を使用した認証のみがサポートされます。詳しい情報については、「personal access tokenの作成」を参照してください。

結果はJSONで返されるので、読んだり検索したりしやすくするために、プリティプリントすることをおすすめします。 jq などのコマンドラインツールを使用したり、この目的のために結果を python -m json.tool にパイプしたりできます。

あるいは、idl メディア型を渡して、IDL 形式で結果を返してもらうこともできます。これはスキーマの圧縮バージョンです。
```
$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
http(s)://HOSTNAME/api/graphql
```
注: イントロスペクションクエリは、おそらく GraphQL で実行する唯一の GET 要求です。本文を渡す場合、GraphQL の要求メソッドは、クエリでもミューテーションでも POST です。

クエリの実行について詳しくは、「GraphQL での呼び出しの作成」を参照してください。