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
フィールドがあります。 カーソルは改ページ位置の自動修正に使用されます。 詳しくは、「GraphQL API 内での改ページ位置の自動修正の使用」を参照してください。
ノード
ノード はオブジェクトの総称です。 ノードは直接ルックアップすることもできますが、コネクションを通じて関連するノードにアクセスすることもできます。 スカラーを返さない 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
応答を受け取った場合は、有効なトークンを使用していることを確認してください。Resource not accessible by personal access token
で403
エラーが発生した場合は、正しいリソース所有者がfine-grained personal access tokenのターゲットとなっていることを確認します。 たとえば、アクセスしようとしているリポジトリを所有している Organization がターゲットにされている必要があります。結果は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での呼び出しの作成」をご覧ください。