GraphQLの紹介

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の下に継承先のオブジェクトを並べます。

コネクション

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

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

エッジ

エッジは、ノード間のコネクションを表します。コネクションに対してクエリを行うと、そのエッジをトラバースしてノードを取得することになります。すべてのedgesフィールドはnodeフィールドとcursorフィールドを持ちます。カーソルはページネーションに使われます。

ノード

ノード はオブジェクトの総称です。ノードは直接ルックアップすることもできますが、コネクションを通じて関連するノードにアクセスすることもできます。スカラーを返さない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というレスポンスが返された� �合は、有効なトークンを使っているか確認してく� さい。詳しい情� �については、「個人アクセストークンを作成する」を参照してく� さい。

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

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