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 固有の新たなフィールドを追加する必要があるということです。 (! はそのフィールドが必須であることを意味します。)

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

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

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での呼び出しの作成」をご覧ください。

この記事の内容

GraphQLの用語

スキーマ

フィールド

引数

実装

Connection

Edge

ノード

GraphQL APIの発見