GitHub API를 써본 개발자라면 대부분 REST API를 먼저 접한다. 다만 복잡한 저장소 정보를 가져올 때 여러 번의 API 호출이 필요하고, 불필요한 필드까지 받게 되는 비효율성을 경험해봤을 가능성이 높다. 이번에는 GraphQL API로 이 문제를 어떻게 해결하는지, 실제로 어떻게 PHP에서 연동하는지 완벽하게 정리해서 소개하겠다.
1단계. GitHub GraphQL API 이해하기
GitHub의 REST API v3는 엔드포인트마다 고정된 데이터 구조를 반환한다. 예를 들어 사용자 정보와 저장소 목록을 동시에 가져오려면 최소 2번 이상의 요청을 해야 한다. 반면 GraphQL API는 클라이언트가 필요한 필드만 명시해서 요청하는 쿼리 방식이다.REST API vs GraphQL의 핵심 차이를 표로 정리하면 다음과 같다.
| 항목 | REST API v3 | GraphQL API |
|---|---|---|
| 요청 방식 | 고정된 엔드포인트 (GET, POST, etc) | 단일 엔드포인트 + 쿼리 본문 |
| 필드 선택 | 정해진 필드 모두 반환 | 필요한 필드만 명시해서 받음 |
| 다중 데이터 조회 | 여러 번의 요청 필요 | 한 번의 쿼리로 처리 |
| 응답 크기 | 불필요한 데이터 포함 | 필요한 것만 포함 |
| Rate Limit | 요청당 1건 계산 | 쿼리 복잡도 기반 |
실제 예제: 사용자 정보 + 저장소 5개 조회
REST API로는 2번 요청이 필요하지만, GraphQL은 한 번에 처리된다. 이것이 GraphQL의 핵심 장점이다.
2단계. GitHub 개인 액세스 토큰(PAT) 발급받기
GitHub GraphQL API를 사용하려면 먼저 인증 토큰이 필요하다.발급 방법:
1. GitHub 계정 로그인 → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. "Generate new token (classic)" 클릭
3. Note: "GitHub GraphQL API" 입력
4. Expiration: 90 days 선택
5. Scopes: "repo" 체크 (저장소 접근 권한)
6. "Generate token" 클릭 후 토큰 복사 (다시 보이지 않음)
3단계. PHP에서 GraphQL 쿼리 실행하기
✓ 올바른 코드: cURL로 GraphQL 요청
<?php
$token = 'github_pat_xxxxxxxxxxxxx'; // 발급받은 토큰
$endpoint = 'https://api.github.com/graphql';
// GraphQL 쿼리 정의
$query =