GraphQLの紹介

GitHub GraphQL APIを利用するための有益な用語と概念を学んでください。

ここには以下の内容があります:

GraphQLの用語
スキーマ
フィールド
引数
Implementation
コネクション
エッジ
ノード
GraphQL APIの発見

GraphQLの用語

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

スキーマ

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

フィールド

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

公式の仕様も、フィールドについて述べています。

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

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

引数

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

Implementation

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

以下は、インターフェース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固有の新たなフィールドを追加しているということです。（!はそのフィールドが必須だという意味です）

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

各オブジェクトは、Implementsの下に継承元のインターフェースを並べます。
各インターフェースは、 Implementationsの下に継承先のオブジェクトを並べます。

__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
```
結果は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での呼び出しの作成」を参照してください。

GraphQLの紹介

Still need help?