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. クエリを送信
    実際にクエリを送信する方法は、ツールやライブラリを使って行うか、プログラムからHTTPリクエストを送信する方法がある。

6. 作り方まとめ

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

全体のまとめ

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

Discussion