Zenn
😶‍🌫️

GraphQLとは

2024/11/30に公開
GitHub
GraphQL
API
クエリ
tech

GraphQLってなに？

GraphQLは、
「データを正確に取ってくるためのリモコン」

普通の方法（REST API）との違い

REST API

  • REST API：「メニューAは全部乗せラーメンです！具材は選べません！」
  • 客：「ネギだけ欲しいんだけど…」

GraphQL

  • GraphQL：「どんな具が欲しい？」
  • 客：「ネギだけください！」

どうやってお願いするの？

GraphQLでは「どんなデータが欲しいか」をクエリで伝えます。

例えばこんなお願い

query {
  repository(owner: "octocat", name: "Hello-World") {
    issues(first: 2) {
      nodes {
        title
        createdAt
      }
    }
  }
}

これの意味は

  1. 「octocatさんのHello-Worldというリポジトリから…」
  2. 「最初の2つのIssueをください。」
  3. 「その中でも、タイトルと作られた日だけが欲しいです！」

結果はこんな感じで返ってくる

{
  "data": {
    "repository": {
      "issues": {
        "nodes": [
          {
            "title": "Fix bug",
            "createdAt": "2024-11-01T00:00:00Z"
          },
          {
            "title": "Update README",
            "createdAt": "2024-11-02T00:00:00Z"
          }
        ]
      }
    }
  }
}

実際に使うには

上の例に挙げたクエリをGitHubのGraphQLエンドポイントに送信すると、指定したリポジトリのイシューデータを取得することができます。GitHubのGraphQL APIエンドポイントは、通常以下のURLです

https://api.github.com/graphql

また、GraphQLはGitHubだけでなく、さまざまなウェブサービスやアプリケーションで使われています。GitHubの他にもFacebook, X, Shopify, Netflixなど、多くのサービスでも利用されています。

GraphQLは、データを効率的にやり取りするための技術であり、特にAPI（アプリケーションプログラミングインターフェース）の設計において広く使用されています。

また、GraphQLでは、複数のリソースにアクセスするために複数のエンドポイントを用意する必要がなく、単一のエンドポイントで済むため、管理がしやすいです。

それぞれのAPIに合ったクエリはどのように作るの？

1. APIのスキーマを理解する

GraphQLは「スキーマ駆動」のAPIです。これは、クエリできるデータの種類や形式がスキーマ（仕様）によって定義されていることを意味します。スキーマを理解することで、どのデータが取得できるのか、どのフィールドが利用可能なのかを知ることができます。

たとえば、GitHubのGraphQL APIでは、リポジトリ、イシュー、プルリクエスト、ユーザー情報など、さまざまなリソース（データ）にアクセスするためのスキーマが定義されています。スキーマは、以下のような情報を提供します：

エンドポイント: データにアクセスするための入口（例: repository、issues）。
フィールド: 取得できる具体的なデータ（例: title、createdAt）。
引数: クエリでデータを絞り込むために使うオプション（例: first、after）。
GitHub GraphQL APIの場合、公式ドキュメントからスキーマ情報を確認できます：

2. GraphQLのクエリの構成を理解する

GraphQLクエリは、リクエストするデータをツリー構造で指定するものです。これを使って、必要な情報を指定して取得します。

# 基本的なクエリ構造
query {
  typeOfData {
    field1
    field2
  }
}

たとえば、GitHubでリポジトリのイシューを取得するには以下のようなクエリを使います：

query {
  repository(owner: "octocat", name: "Hello-World") {
    issues(first: 10) {
      nodes {
        title
        createdAt
        state
      }
    }
  }
}

この例では、repositoryからissuesを取得し、そのissuesの中にtitle、createdAt、stateという情報を取得しています。

3. 具体的なAPIに合わせたクエリを作成する

各APIには特定のリソースに対するクエリが用意されています。例えば、GitHubのGraphQL APIでは、リポジトリ、イシュー、プルリクエストなどを扱うためのクエリが用意されています。他のAPIでも同じように、データに合わせてクエリを作成します。

以下は、GitHub APIにおけるいくつかの例です。

リポジトリ情報を取得するクエリ
リポジトリ名、所有者の情報を取得するクエリ：

query {
  repository(owner: "octocat", name: "Hello-World") {
    name
    owner {
      login
    }
    description
  }
}

イシュー情報を取得するクエリ
イシューのタイトルや作成日時、状態を取得するクエリ：

query {
  repository(owner: "octocat", name: "Hello-World") {
    issues(first: 5) {
      nodes {
        title
        createdAt
        state
      }
    }
  }
}

ユーザー情報を取得するクエリ
GitHubユーザーのプロフィール情報を取得するクエリ：

query {
  user(login: "octocat") {
    name
    bio
    repositories(first: 5) {
      nodes {
        name
      }
    }
  }
}

4. 複雑なクエリを作成する

クエリは複数のデータリソースを組み合わせて、必要な情報を一度に取得することができます。たとえば、リポジトリ内のイシューとそのコメントを一度に取得したい場合、以下のように複雑なクエリを作成できます：

query {
  repository(owner: "octocat", name: "Hello-World") {
    issues(first: 5) {
      nodes {
        title
        createdAt
        comments(first: 3) {
          nodes {
            body
            createdAt
          }
        }
      }
    }
  }
}

このクエリは、octocatのHello-Worldリポジトリの最初の5つのイシューについて、各イシューのタイトル、作成日時とそのコメントを最大3件まで取得します。

5. クエリの実行方法

作成したGraphQLクエリを実際に使うためには、以下の手順で実行します：

  1. GraphQLエンドポイントにリクエストを送る
    GitHubの場合、エンドポイントは https://api.github.com/graphqlです。このURLにHTTPリクエストを送ります。

  2. 認証情報の設定
    多くのAPIは認証が必要です。GitHubのGraphQL APIの場合、Personal Access Tokenをヘッダーに追加して認証します。

  3. クエリを送信
    実際にクエリを送信する方法は、ツールやライブラリを使って行います。例えば、Postman や Insomnia などのツールを使う、またはプログラムからHTTPリクエストを送信する方法があります。

6. 作り方まとめ

GraphQLクエリを作成するには、APIのスキーマを理解し、必要なデータをどのようにリクエストするかを考えることが重要です。それぞれのAPIに特化したクエリを作成するには、各APIのドキュメントにあるリソースやフィールドの構造を確認し、適切な引数を設定してクエリを組み立てていきます。

全体のまとめ

GraphQLは、自分が欲しい情報だけを正確に引き出すためのリモコンです！
使い方を覚えると、必要なデータだけを効率よく取れるので便利です。

Discussion