はじめに

GitLabを使う時に、APIを通じてデータを取得したりプロジェクトを操作したりする機会は多いのではないでしょうか。GitLabでは従来のREST APIに加えて、GraphQL APIも提供されています。

本記事では、GitLab GraphQL APIの特徴やメリット・デメリット、そして実際の使用例を通じて、どのような場面でGraphQLを選択すべきかを書いていきます。

GraphQL APIを使うメリット

必要なデータのみを取得できる

GraphQLの最大の特徴は、クエリで必要なフィールドを明示的に指定できることです。REST APIでは不要なデータも含めて全てが返されますが、GraphQLなら本当に必要な情報だけを取得できます。

例えば、100個のプロジェクトから名前とIDだけが必要な場合、REST APIでは全プロジェクトデータが返されますが、GraphQLならごくわずかのデータで済みます。モバイルアプリケーションなど、通信量を削減したい場面では特に有効です。

複数リソースを1回のリクエストで取得

REST APIでは、関連するデータを取得するために複数のエンドポイントにアクセスする必要がありますが、GraphQLなら1つのクエリで全てを取得できます。

例えば、プロジェクト情報とそのイシュー、マージリクエストを同時に取得したい場合、REST APIでは最低でも3回のHTTPリクエストが必要ですが、GraphQLなら1回で完結します。これによりレイテンシーを大幅に削減できます。

型安全性とスキーマ

GraphQLはスキーマで型が厳密に定義されているため、どのようなデータが返されるかが明確です。また、GitLabのGraphQL Explorerなどのツールを使えば、対話的にクエリを構築でき、開発効率が向上します。

オーバーフェッチング・アンダーフェッチングの解消

REST APIでよくある問題として、必要以上のデータを取得してしまう（オーバーフェッチング）、または追加のリクエストが必要になる（アンダーフェッチング）があります。GraphQLではこれらの問題を根本的に解決できます。

GraphQL APIのデメリット

学習コスト

GraphQLのクエリ言語、ミューテーション、スキーマの概念など、REST APIに比べて学習すべき内容が多くなります。チーム全体でGraphQLを採用する場合、教育コストも考慮する必要があります。

クエリの複雑性

シンプルな操作でも、GraphQLではクエリを構造化して記述する必要があります。単純なGET/POSTで済むREST APIと比較すると、記述量が増えることがあります。

キャッシュの難しさ

REST APIはURLベースで簡単にキャッシュできますが、GraphQLは単一エンドポイントでPOSTリクエストを使用するため、HTTPレベルでのキャッシュが効きにくくなります。アプリケーション層でのキャッシュ戦略を別途検討する必要があります。

エラーハンドリングの複雑さ

GraphQLは部分的な成功を返すことがあり、HTTPステータスコードだけでなく、レスポンス内のエラーフィールドも確認する必要があります。これにより、エラーハンドリングのロジックが複雑になる場合があります。

レート制限の管理

GitLabのGraphQL APIには複雑度に基づくレート制限があります。クエリの複雑さによって消費されるポイントが変わるため、REST APIの単純な回数制限と比べて管理が難しくなることがあります。

セキュリティに関する考慮点

GraphQLは柔軟なクエリが書ける反面、悪意のあるユーザーが極端に深いネストや大量のデータを要求するクエリを実行することで、サーバーに過度な負荷をかける可能性があります（DoS攻撃のリスク）。

GitLabはこのリスクに対して、クエリ複雑度制限という仕組みで対策しています。各フィールドに「コスト」が設定されており、クエリ全体のコストが上限を超えると実行が拒否されます。この仕組みにより、サーバーリソースを保護しつつ、正当な利用には影響を与えないようバランスが取られています。

パフォーマンスの観点から

ネットワーク効率

GraphQLは必要なデータのみを取得するため、ネットワーク帯域の使用効率が高くなります。特に以下のような場合に有効です：

大量のデータから特定のフィールドのみが必要な場合
関連する複数のリソースを一度に取得する場合

サーバー側の処理負荷

一方で、複雑なクエリはサーバー側で多数のデータベースクエリを発生させる可能性があります。深くネストしたクエリや多数の関連リソースを取得する場合は、REST APIより処理時間が長くなることもあります。

実際の使い分け

GraphQLが有利な場合

複数のプロジェクトとその関連データを一度に取得
例：50個のプロジェクトとそれぞれの最新10イシューを取得
- REST: 51回のAPIコール（数秒）
- GraphQL: 1回のAPIコール（数百ミリ秒）
モバイルアプリなど帯域幅を節約したい場合
フロントエンドで柔軟にデータを取得したい場合
大量のデータから特定のフィールドのみを抽出する場合

REST APIが適している場合

シンプルなCRUD操作
既存のツールやライブラリとの統合
学習コストを抑えたい場合
HTTPキャッシュを活用したい場合

実装例で見る違い

例1: プロジェクトの基本情報取得

REST API: (doc)

curl --header "PRIVATE-TOKEN: <your_token>" \
  "https://gitlab.example.com/api/v4/projects/123"

GraphQL API: (doc) (doc)

{
  project(fullPath: "group/my-project") {
    id
    name
    description
    createdAt
    visibility
    starCount
    forksCount
  }
}

curlで実行するコマンドラインとしては

curl "https://gitlab.example.com/api/graphql" \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data @- << EOF
   { "query": "query 
        {  project(fullPath: \"group/my-project\") {
            id 
            name 
            description 
            createdAt 
            visibility 
            starCount
            forksCount
           }
        }"
    }
EOF

REST APIは50以上のフィールドを含む全データを返しますが、GraphQLでは必要な7つのフィールドのみを取得できます。

例2: プロジェクトのイシュー一覧とアサイン情報

REST API: (doc)

# 1. プロジェクトのイシュー一覧を取得
curl --header "PRIVATE-TOKEN: <your_token>" \
  "https://gitlab.example.com/api/v4/projects/123/issues?state=opened&per_page=10"

# 2. 各イシューのアサイン情報を個別に取得（必要に応じて）
curl --header "PRIVATE-TOKEN: <your_token>" \
  "https://gitlab.example.com/api/v4/projects/123/issues/1"

GraphQL API: (doc) (doc)

query {
  project(fullPath: "group/my-project") {
    name
    issues(state: opened, first: 10) {
      nodes {
        iid
        title
        state
        createdAt
        author {
          username
          name
        }
        assignees {
          nodes {
            username
            name
          }
        }
      }
    }
  }
}

例3: イシューの作成

REST API: (doc)

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "New Issue",
    "description": "Issue description",
    "assignee_ids": [1, 2],
    "labels": ["bug", "priority::high"]
  }' \
  "https://gitlab.example.com/api/v4/projects/123/issues"

GraphQL API: (doc)

mutation {
  createIssue(input: {
    projectPath: "group/my-project"
    title: "New Issue"
    description: "Issue description"
    assigneeIds: ["gid://gitlab/User/1", "gid://gitlab/User/2"]
    labels: ["bug", "priority::high"]
  }) {
    issue {
      iid
      webUrl
      title
    }
    errors
  }
}

例4: 単一グループ内の複数プロジェクトとその最新マージリクエスト

REST API（Python）:

import requests

headers = {"PRIVATE-TOKEN": "<your_token>"}
base_url = "https://gitlab.example.com/api/v4"

# 1. グループのプロジェクト一覧を取得
projects_response = requests.get(
    f"{base_url}/groups/5/projects",
    headers=headers,
    params={"per_page": 5}
)
projects = projects_response.json()

# 2. 各プロジェクトのマージリクエストを個別に取得
for project in projects:
    mr_response = requests.get(
        f"{base_url}/projects/{project['id']}/merge_requests",
        headers=headers,
        params={"state": "opened", "per_page": 3}
    )
    merge_requests = mr_response.json()
    # 合計6回のAPIコール（1 + 5）

GraphQL API（Python）:

import requests

query = """
query {
  group(fullPath: "my-group") {
    projects(first: 5) {
      nodes {
        name
        webUrl
        mergeRequests(state: opened, first: 3) {
          nodes {
            iid
            title
            sourceBranch
            targetBranch
            author {
              username
            }
          }
        }
      }
    }
  }
}
"""

response = requests.post(
    "https://gitlab.example.com/api/graphql",
    headers={"Authorization": f"Bearer {token}"},
    json={"query": query}
)
# 1回のAPIコールで全データ取得

実測パフォーマンス比較

実際のスクリプトで「プロジェクト詳細、イシュー10件、各イシューの担当者情報」を取得した場合の比較結果：

指標	REST API	GraphQL API	改善率
API呼び出し回数	12回	1回	92%削減
実行時間	6.23秒	0.41秒	93%短縮
データ転送量	114.4KB	2.7KB	98%削減
コード行数	80行	43行	46%削減

特に複数のリソースを関連付けて取得する必要がある場合、GraphQL APIの優位性が顕著に現れます。REST APIではN+1問題が発生しやすく、データ量が増えるほどパフォーマンスの差が広がります。

ご参考までに、計測に使用したスクリプトを置いておきます。

GitLab GraphQL Explorerの活用

GitLabには、GraphQL APIを対話的に探索・テストできる強力なツール「GraphQL Explorer」が組み込まれています。これは、GraphQL APIを使い始める際の最も便利な機能の一つです。

アクセス方法

GitLabインスタンスの以下のURLにアクセスするだけで利用できます：

https://<GitLab URL>/-/graphql-explorer

主な機能

スキーマブラウザ

左側のパネルで、利用可能な全てのクエリ、ミューテーション、型定義を確認できます。各フィールドをクリックすると、以下の情報が表示されます：

フィールドの説明
引数の詳細
返却される型
非推奨情報（ある場合）

クエリエディタ

中央のエディタでクエリを作成できます。主な特徴：

自動補完機能: フィールド名を入力中に候補を表示
シンタックスハイライト: GraphQLの構文を色分けして表示
エラー検出: 構文エラーや型の不一致をリアルタイムで検出
フォーマット機能: Prettifyボタンでクエリを整形

変数エディタ

クエリで使用する変数をJSON形式で定義できます：

{
  "projectPath": "group/my-project",
  "issueCount": 10
}

レスポンスビューア

右側のパネルに実行結果が表示されます。JSONフォーマットで見やすく整形され、折りたたみ機能も利用できます。

実際の使用例

ステップ1: 探索的なクエリ構築

# まず利用可能なフィールドを確認
{
  currentUser {
    # "CurrentUser" をクリックしてドキュメント表示
  }
}

ステップ2: 段階的な拡張

{
  currentUser {
    username
    name
    # projectsを追加
    projectMemberships {
      nodes {
        project {
          name
          id
          visibility
        }
      }
    }
  }
}

ステップ3: 引数の追加

{
  project(fullPath: "gitlab-org/gitlab") {
    name
    issues(state: opened, first: 5) {
      nodes {
        title
        createdAt
      }
    }
  }
}

便利な機能

History機能

実行したクエリの履歴が保存され、過去のクエリを簡単に再利用できます。

ドキュメント参照

各フィールドをクリックすると、詳細なドキュメントが表示されます。

開発フローへの組み込み

プロトタイピング: Explorerでクエリを作成・テスト
最適化: クエリコストを確認しながら効率的なクエリに調整
実装: 完成したクエリをアプリケーションコードに組み込み

GraphQL Explorerを活用することで、APIリファレンスを参照しつつ、試行錯誤しながら最適なクエリを構築できます。

まとめ

GitLab GraphQL APIは、適切に使用すれば開発効率とパフォーマンスを大幅に向上させることができます。特に複雑なデータ取得が必要な場面では、その真価を発揮します。

一方で、全てのケースでGraphQLが優れているわけではありません。シンプルな操作にはREST APIの方が適している場合もあります。プロジェクトの要件、チームのスキルセット、そして各APIの特性を理解した上で、適切に使い分けることが重要です。

GitLabのGraphQL Explorerを使って、まずは簡単なクエリから始めてみてはいかがでしょうか。きっと、その柔軟性と効率性に驚かれることでしょう。