GitHub 별 이력 API, 사라진 별까지 보여줄까?

세 줄 요약

GitHub의 별 이력 API는 사용자 목록 없이 주별·일별 별 개수를 제공한다.
한 번에 최대 30주를 조회하며, 공개 저장소는 인증 없이 접근할 수 있다.
지금 남아 있는 별의 생성일을 집계하므로 과거의 별 취소와 일별 순증감을 재현하지는 않는다.

사람 목록이 필요 없는 그래프에는 집계 API가 있다

GitHub 별 증가 그래프를 만들기 위해 저장소에 별을 누른 사람을 모두 받아올 필요가 없어졌다. GitHub가 8월 28일 공개한 이력 엔드포인트는 개인 식별자 없이 주별·일별 집계를 돌려준다. 10월 14일에는 이 API의 설계를 설명하는 기술 글이 나왔다.

배경에는 stargazer·watcher 목록의 관리자·협업자 접근 제한이 있다. 사람 목록을 받아 별을 누른 시점만 추출하던 도구도 영향을 받았다. 기존 목록 호출의 권한을 그대로 요구하는 대신, 그래프에 필요한 날짜와 개수를 따로 제공한 것이다.

30개 별이 아니라 최대 30주를 받는다

공식 REST 명세의 경로는 다음과 같다. OWNER와 REPO에는 대상 계정과 저장소 이름이 들어간다.

GET /repos/OWNER/REPO/stargazers/history?per_page=30&page=1

항목	읽는 법
`per_page`	페이지당 주 수다. 기본값과 최대값은 30이다.
`page`	기본값은 1, 최대값은 100이다. 커질수록 과거로 이동한다.
`days`	일요일부터 시작하는 일별 개수 배열이다.
주·일 경계	UTC와 일치한다고 보장하지 않는다.

별이 없는 주도 0으로 채워지며, 페이지 안의 주는 최신순이다. 공개 리소스만 요청하면 인증이 필요 없다. 세분화된 토큰을 사용하는 경우에는 저장소의 Metadata 읽기 권한이 명시돼 있다.

응답을 줄이는 것보다 먼저 읽을 행을 줄였다

GitHub의 10월 기술 해설은 약 25만 1,000개의 별이 있는 react/react 사례를 제시한다. 과거 방식으로 전체 곡선을 얻으려면 약 2,511회 요청이 필요했지만 새 방식에서는 약 24회로 줄었다.

핵심은 집계 순서다. 모든 별을 날짜별로 묶은 뒤 결과 일부만 반환하면 데이터베이스는 이미 전체 집계를 수행한 상태다. 새 방식은 조회할 주의 날짜 범위부터 좁힌 뒤 해당 구간을 집계한다. 다만 한 주에 별이 집중되면 그 구간의 처리 비용은 여전히 커질 수 있다. 요청 횟수 감소를 모든 저장소의 실행 속도 배수로 읽어서는 안 된다.

별이 줄어든 날을 찾는 용도로는 부족하다

이 API는 취소된 별의 이력을 보관하지 않는다. 공식 발표 글의 9월 11일 답변에서 moraesc는 현재 유효한 별만 생성일별로 반환한다고 설명했다.

따라서 그래프의 날짜별 숫자를 당시 전체 별 수의 순증감으로 표시하면 의미가 달라진다. 취소가 언제 일어났는지 되짚는 자료로 쓸 수 없기 때문이다. 대시보드에는 ‘현재 남은 별의 생성일 분포’라는 의미가 드러나도록 표시하는 편이 정확하다.

자주 묻는 질문

공개 저장소의 협업자가 아니어도 조회할 수 있는가?

공개 이력 엔드포인트는 무인증 요청을 허용한다. stargazer 개인 목록과 접근 조건이 다르다.

별 증가 곡선이 곧 프로젝트 사용량인가?

아니다. 별 이력은 저장소에 표시한 관심을 나타내는 자료다. API 응답에 앱 사용량이나 다운로드 수가 들어 있는 것은 아니다.

추세를 보여줄 도구라면 집계 API로 옮길 수 있다. 다만 그래프의 이름과 설명도 데이터가 실제로 뜻하는 범위에 맞춰야 한다.