GitHub API v4를 적절한 지식으로 사용해보기

문서

GraphQL API v4 - GitHub Developer

GraphQL API v4 - GitHub Developer (Enterprise)

GraphQL 클라이언트 선택

GraphQL API를 부르는 클라이언트는 다양하다.

GraphiQL

Altair GraphQL 클라이언트 ( Chrome extension )

GitHub GraphQL API Explorer

GitHub API 전용의 GitHub GraphQL API Explorer를 사용하는 것이 빠를지도 모르지만, 여기에서는 Altair (알타일)를 사용해 본다.

Altair 시작

사이트에서 Altair의 Chrome extension을 설치하고 시작하면 다음과 같은 화면이 표시되므로 엔드포인트에 다음을 입력하고 재밌게 'Send Request'해 봅니다. 당연히 인증 오류가 발생합니다.

GitHub https://api.github.com/graphql

GitHub Enterprise의 경우 http(s)://[hostname]/api/graphql

인증

GitHub에 로그인하고 Settings > Developer Settings > Personal access tokens에서 "Generate new token"을 실행합니다. Scopes는 API 호출에 필요한 권한을 선택합니다. 여기서 설정한 권한에 부족이 있는 경우는 API 실행시에 허가 에러가 되지만, 나중에 설정 변경도 할 수 있으므로 우선은 적당하게. 우선 이상한 일은 할 수 없도록 Read계만으로 하는 것이 무난할지도.



액세스 토큰은 한 번만 표시되므로 메모해 둡니다.



생성된 액세스 토큰을 Altair로 설정합니다. 화면 왼쪽의 네비게이션에서 "Set Headers"를 클릭하고 다음과 같이 입력합니다. 이제 모든 후속 요청에 설정된 헤더가 전송됩니다.


Header key
Header value


Authorization
bearer (액세스 토큰)

API 문서 참조

"Send Request"의 왼쪽에 있는 "Docs"를 클릭하고, 그 왼쪽의 "Reload Docs"를 클릭한다. 인증이 성공적으로 통과되면 API 문서가 표시됩니다. "Query"는 읽기 API, "Mutation"은 쓰기 API로 나뉘어 있으므로 우선 "Query"를 클릭합니다. API 목록이 표시되므로 원하는 것을 호버하고 표시되는 ADD QUERY 버튼을 클릭합니다. 이제 API를 호출하는 쿼리의 병아리가 쿼리 창에 설정됩니다.

예를 들어 user 의 쿼리는 다음과 같이 된다.

query{
  user(login: ______){
    anyPinnableItems(type: ______)
    avatarUrl(size: ______)
    bio
    bioHTML
    ...
  }
}

우선은 얼른 다음과 같은 인식으로 OK. 채울 필요가 있는 곳은 「______」가 되어 있어 그대로는 에러가 되므로, 조건을 메우거나, 취득할 필요가 없는 것은 삭제하거나 하고 에러가 사라지면 「Send Request」를 행한다.

query {
    欲しいもの(条件) {
        欲しいもの
    }
}

실행 예

잡혔다.

요약

GraphQL 에서는 API 사양이 구현에 직결한 형태로 취득할 수 있으므로, 쿼리를 자동 생성하는 구조도 클라이언트로 구현하기 쉽고, 문서와 망설임 없이도 적당하게 호출해 볼 수 있다. GraphQL 로서, 읽기 전용의 「Query」와, 기입이 발생하는 「Mutation」이 명확하게 나뉘어져 있으므로, Query 만이라면 얼마든지 시험해 보면 좋다고 생각한다. GitHub의 API 문서는 별도이지만 정직하고 어렵기 때문에 강력한 도구를 활용하여 이해합시다!