今年の春、開発チーム内で「GitHubの情報を使って開発状況を見える化できないか」という議論がありました。
調査の結果、GitHubはRESTとGraphQLの2種類のAPIを提供しており、いずれもデータの取得や更新に利用できます。
今回は簡単な例として、同じデータ（リポジトリ一覧）をREST APIとGraphQL APIの両方で取得し、それぞれの扱いやすさや設計思想の違いを比較します。
目次
1. GitHub APIの概要（RESTとGraphQLの違い）
2. REST APIでリポジトリ一覧取得
3. GraphQL APIでリポジトリ一覧取得
4. GitHub APIテスト環境のセットアップ手順
5. GraphQLクエリを変更しよう
6. API バージョンについて
7. さいごに
1.GitHub APIの概要（RESTとGraphQLの違い）
GitHubは開発者向けにRESTとGraphQLの2種類のAPIを提供しています。
それぞれの特徴は以下の通りです。
REST API
REST APIは、複数のエンドポイントに対してHTTPメソッド（GET、POSTなど）でアクセスするリソース指向の設計が特徴です。
レスポンス構造はエンドポイントごとに固定されており、HTTPの標準機能（キャッシュ、条件付きリクエスト、ステータスコードなど）を活用しやすいという利点があります。
シンプルで扱いやすく、特に一覧取得やプロトタイピングに適しています。
GraphQL API
GraphQL APIは、単一のエンドポイントに対して、必要な項目だけをクエリで明示的に指定して取得できる柔軟な設計が特徴です。
REST APIと異なり、クライアント側でのキャッシュ設計を必要としますが、必要な情報だけを効率的に、複数リソースを横断して取得できるという利点があります。
2.REST APIでリポジトリ一覧取得
REST APIでリポジトリ一覧を取得するには、リポジトリ取得用のエンドポイントにアクセスする必要があります。
たとえば、認証ユーザーのリポジトリ一覧を取得する場合、以下のエンドポイントでアクセスします。
GET https://api.github.com/user/repos |
以下は、認証ユーザーのリポジトリ一覧を取得するPythonのサンプルコードです。
アクセス先エンドポイントは、url変数で指定しています。
【rest_sample.py】
import os |
import requests |
from dotenv import load_dotenv |
# 環境変数からアクセストークンを取得 |
load_dotenv() |
token = os.getenv('GITHUB_TOKEN') |
# リクエストヘッダー |
headers = {'Authorization': f'Bearer {token}', 'Accept': 'application/vnd.github+json'} |
# エンドポイント |
url = 'https://api.github.com/user/repos' |
# クエリパラメータ |
params = { |
'visibility': 'all', # 公開・非公開すべてのリポジトリを対象 |
'affiliation': 'owner,collaborator', # 自分がオーナーまたはコラボレーターのリポジトリ |
'sort': 'created', # 作成日時でソート |
'direction': 'desc', # 新しい順に並べる |
} |
# リクエスト送信 |
response = requests.get(url, headers=headers, params=params) |
# レスポンス確認 |
if response.status_code == 200: |
repos = response.json() |
print('Repository list:') |
for repo in repos: |
print(f'- {repo["name"]}') |
else: |
print(f'Error: {response.status_code}') |
このように、GET /user/repos で認証ユーザーのリポジトリ一覧を取得できますが、これ以外にも用途に応じたリポジトリ一覧取得のエンドポイントが用意されています。
- 特定ユーザーのリポジトリ一覧（GET /users/{username}/repos）
- 特定トピック付きのリポジトリ一覧（GET /search/repositories）
リポジトリ取得用のエンドポイントは、次の公式ドキュメントで確認できます。
3.GraphQL APIでリポジトリ一覧取得
GraphQLの場合は、リポジトリ一覧を取得するエンドポイントは以下の1つだけです。
POST https://api.github.com/graphql |
クエリでは必要な項目を明示的に指定できるため、リポジトリのnameのみを取得することができます。
以下は、認証ユーザーのリポジトリ一覧を取得するPythonのサンプルコードです。
アクセス先エンドポイントは、url変数で指定しています。
【graphql_sample.py】
import os |
import requests |
from dotenv import load_dotenv |
# 環境変数からアクセストークンを取得 |
load_dotenv() |
token = os.getenv('GITHUB_TOKEN') |
# リクエストヘッダー |
headers = {'Authorization': f'Bearer {token}', 'Content-Type': 'application/json'} |
# エンドポイント |
url = 'https://api.github.com/graphql' |
# GraphQLクエリ（リポジトリ名のみ取得） |
query = """ |
{ |
viewer { # ログイン中のユーザーの情報を取得 |
repositories( # ユーザーが関わっているリポジトリ一覧を取得する |
first: 100, # 最大100件まで取得 |
affiliations: [OWNER, COLLABORATOR], # 自分がオーナーまたはコラボレーターのリポジトリ |
orderBy: {field: CREATED_AT, direction: DESC} # 作成日時の降順（新しい順）で並べる |
) { |
nodes { # 実際のリポジトリのデータを表す |
name # 各リポジトリの名前だけを取得 |
} |
} |
} |
} |
""" |
# リクエスト送信 |
response = requests.post(url, headers=headers, json={'query': query}) |
# レスポンス確認 |
if response.status_code == 200: |
data = response.json() |
repos = data['data']['viewer']['repositories']['nodes'] |
print('Repository list:') |
for repo in repos: |
print(f'- {repo["name"]}') |
else: |
print(f'Error: {response.status_code}') |
4.GitHub APIテスト環境のセットアップ手順
サンプルコードの実行に必要な手順を以下にまとめました。
- 使用環境（参考）
・OS：Windows 11
・開発環境：Visual Studio Code（VS Code）+ Python 3.11.9
・仮想環境：venv を使用し、VS Codeのターミナルから実行
- ディレクトリ構成
github_api_test/ フォルダを作成し、以下のようにファイルを格納します。
github_api_test/ |
|-.env：GitHubのアクセストークンなどの環境変数 |
|-requirements.txt：必要なPythonパッケージ |
|-rest_sample.py：REST APIでリポジトリ一覧を取得するコード |
|-graphql_sample.py：GraphQL APIでリポジトリ一覧を取得するコード |
- .envファイルを編集
GitHub APIを利用するには、Personal Access Token（PAT）が必要です。
PATを以下の手順で取得し、.envファイルに定義されているGitHubのアクセストークン（GITHUB_TOKEN）に設定します。- GitHubにログイン
- Settings-> Developer settings-> Personal access tokens-> Tokens (classic)を選択し、「Generate new token」を実行
- 必要な権限で「repo」（リポジトリ関連の操作）を選択
- 有効期限を設定し、「Generate token」をクリック
- 表示されたPATをコピーし、 .envファイルに記述
※注意：PATは一度しか表示されません。
| GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxx |
※注意：.envはリポジトリにコミットしないでください（.gitignoreに追加）
- requirements.txtを編集
Pythonで使用するライブラリを記述します。
requests |
python-dotenv |
- 実行手順（VS Code）
venv を使用し、VS Codeのターミナルから実行します。
# 仮想環境作成 |
python -m venv venv |
# 仮想環境を有効化（Windows） |
.\venv\Scripts\activate |
# ライブラリをインストール |
pip install -r requirements.txt |
# 実行（例：GraphQL） |
python graphql_sample.py |
- 実行結果の確認
rest_sample.pyとgraphql_sample.pyを実行し、ターミナルにリポジトリ一覧が表示されていることを確認してください。
表示されるのは、自分がオーナーまたはコラボレーターのリポジトリです。
| Repository list: - sampleA-repository - sampleB-repository - sampleC-repository |
5.GraphQLクエリを変更しよう
graphql_sample.pyが問題なく動作したら、GraphQLクエリを変更しましょう。
まず、各リポジトリのOPEN状態のPull Request（PR）の件数を取得するために、 pullRequestsフィールドを追加します。
nodes { # 実際のリポジトリのデータを表す |
name # 各リポジトリの名前だけを取得 |
pullRequests(states: OPEN) { |
totalCount # OPEN状態のPRの件数を取得 |
} |
次に、レスポンス確認の出力処理を以下のように変更します。
print('Repository list:') |
for repo in repos: |
repo_name = repo['name'] |
open_pr_count = repo['pullRequests']['totalCount'] |
print(f'- {repo_name}: PR OPEN({open_pr_count})') |
変更したgraphql_sample.pyを実行し、ターミナルにリポジトリ一覧とOPEN状態のPRの件数が表示されていることを確認してください。
| Repository list: - sampleA-repository: PR OPEN(4) - sampleB-repository: PR OPEN(0) - sampleC-repository: PR OPEN(1) |
もし、OPEN状態のPRが存在しない場合は、pullRequestsフィールドのstatesをMERGEDやCLOSEDに変更して試すこともできます。
6.APIバージョンについて
本記事の動作確認は、2025年10月時点でサポートされている安定版の以下の API バージョンを使用して行いました。
・GitHub REST API v3（現行バージョン日付：2022-11-28）
・GitHub GraphQL API v4（随時更新）
REST API v3 では、公式ドキュメントに掲載されている一部のエンドポイントが、今後廃止予定またはすでに廃止済みとなっている場合があります。
非推奨のエンドポイントを利用すると、予期せぬエラーや動作の不一致が発生する可能性があるため、REST API を利用する際は、現行仕様に準拠し、安定版バージョンとサポート状況を確認した上での実装をおすすめします。
GraphQL API v4 は、スキーマが随時更新される形式で提供されており、変更が頻繁に行われています。
各API の変更履歴や最新情報については、GitHub の公式ページをご確認ください。
7.さいごに
実際にGraphQL APIを使っていくと、欲しい情報を効率よく取得できました。
ただ、私自身は、GitHub GraphQL API documentation - GitHub Docsを参考に学習を進めたのですが、クエリの書き方や構造を理解するのに少し時間がかかってしまいました。
そのため、GitHubのデータ取得を手軽に試したい方や、APIの仕組みに触れてみたい方は、まずはREST APIから始めるのがおすすめです。
目的に応じてRESTとGraphQLを使い分けることで、GitHubの情報を有効に活用していきたいですね。
