REST API 사용에 대한 모범 사례

폴링 방지

데이터에 대한 API를 폴링하는 대신 웹후크 이벤트를 구독해야 합니다. 이렇게 하면 통합이 API 트래픽률 제한 내에서 유지됩니다. 자세한 내용은 웹후크 설명서을(를) 참조하세요.

요청 인증하기

인증된 요청은 인증되지 않은 요청보다 기본 속도 제한이 높습니다. 속도 제한을 초과하지 않도록 하려면 인증된 요청을 수행해야 합니다. 자세한 내용은 REST API에 대한 트래픽률 제한을(를) 참조하세요.

동시 요청 금지

보조 속도 제한을 초과하지 않도록 하려면 동시에 요청하지 않고 직렬로 요청해야 합니다. 이를 위해 요청에 대한 큐 시스템을 구현할 수 있습니다.

변경 요청 간 일시 중지

많은 수의 POST, PATCH, PUT 또는 DELETE 요청을 만드는 경우 각 요청 사이에 1초 이상 기다립니다. 이를 통해 보조 속도 제한을 방지할 수 있습니다.

속도 제한 오류를 적절하게 처리

트래픽률 제한 오류를 수신하는 경우 다음 지침에 따라 일시적으로 요청을 중지해야 합니다.

• retry-after 응답 헤더가 있는 경우 몇 초가 경과할 때까지 요청을 다시 시도하면 안 됩니다.
• x-ratelimit-remaining 헤더가 0인 경우 x-ratelimit-reset 헤더로 지정된 시간까지 다른 요청을 시도해서는 안 됩니다. 헤더는 x-ratelimit-reset UTC Epoch 초 단위입니다.
• 그렇지 않은 경우 다시 시도하기 전에 1분 이상 기다립니다. 보조 트래픽률 제한으로 인해 요청이 계속 실패하는 경우 재시도 사이에 기하급수적으로 증가하는 시간을 기다린 후 특정 횟수의 재시도 후 오류가 발생합니다.

트래픽률이 제한된 동안 요청을 계속하면 통합이 금지될 수 있습니다.

리디렉션 따르기

GitHub REST API는 적절한 경우 HTTP 리디렉션을 사용합니다. 사용자는 모든 요청이 리디렉션을 초래할 수 있다고 가정해야 합니다. HTTP 리디렉션을 받는 것은 오류가 아니며 사용자는 해당 리디렉션을 따라야 합니다.

301 상태 코드는 영구 리디렉션을 나타냅니다. location 헤더에 지정된 URL에 대한 요청을 반복해야 합니다. 또한 이후 요청에 이 URL을 사용하도록 코드를 업데이트해야 합니다.

302 또는 307 상태 코드는 임시 리디렉션을 나타냅니다. location 헤더에 지정된 URL에 대한 요청을 반복해야 합니다. 그러나 이후 요청에 이 URL을 사용하도록 코드를 업데이트해서는 안 됩니다.

다른 리디렉션 상태 코드는 HTTP 사양에 따라 사용될 수 있습니다.

URL의 수동 구문 분석 금지

많은 API 엔드포인트는 응답 본문의 필드에 대한 URL 값을 반환합니다. 이러한 URL을 구문 분석하거나 향후 URL의 구조를 예측해서는 안 됩니다. 이로 인해 GitHub이(가) 나중에 URL의 구조를 변경하는 경우 통합이 중단될 수 있습니다. 대신 필요한 정보가 포함된 필드를 찾아야 합니다. 예를 들어 문제를 만드는 엔드포인트는 https://github.com/octocat/Hello-World/issues/1347과 같은 값이 있는 html_url 필드와 1347과 같은 값이 있는 number 필드를 반환합니다. 문제의 수를 알아야 하는 경우 html_url 필드를 구문 분석하는 대신 number 필드를 사용합니다.

마찬가지로 페이지를 매긴 쿼리를 수동으로 생성해서는 안 됩니다. 대신 링크 헤더를 사용하여 요청할 수 있는 결과의 페이지를 결정해야 합니다. 자세한 내용은 REST API에서 페이지 매김 사용을(를) 참조하세요.

적절한 경우 조건부 요청 사용

대부분의 엔드포인트는 etag 헤더를 반환하고 많은 엔드포인트는 last-modified 헤더를 반환합니다. 이러한 헤더의 값을 사용하여 조건부 GET 요청을 수행할 수 있습니다. 응답이 변경되지 않은 경우 304 Not Modified 응답을 받게 됩니다. 조건부 요청을 수행했을 때, 304 응답이 반환되고 Authorization 헤더로 올바르게 인증된 상태에서 요청이 이루어진 경우, 해당 요청은 기본 속도 제한에 포함되지 않습니다.

예를 들어 이전 요청이 644b5b0155e6404a9cc4bd9d8b1ae730의 etag 헤더 값을 반환한 경우 이후 요청에서 if-none-match 헤더를 사용할 수 있습니다.

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.github.com/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'

예를 들어 이전 요청이 Wed, 25 Oct 2023 19:17:59 GMT의 last-modified 헤더 값을 반환한 경우 이후 요청에서 if-modified-since 헤더를 사용할 수 있습니다.

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.github.com/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'

특정 엔드포인트에 대한 설명서에 달리 명시되지 않는 한 POST, PUT, PATCH, DELETE 등의 안전하지 않은 메서드에 대한 조건부 요청은 지원되지 않습니다.

오류 무시 금지

반복되는 4xx 및 5xx 오류 코드를 무시해서는 안 됩니다. 대신 API와 올바르게 상호 작용하고 있는지 확인해야 합니다. 예를 들어 엔드포인트가 문자열을 요청하고 사용자가 숫자 값을 전달하면 유효성 검사 오류가 수신됩니다. 마찬가지로 권한이 없거나 존재하지 않는 엔드포인트에 액세스하려고 하면 4xx 오류가 발생합니다.

반복된 유효성 검사 오류를 의도적으로 무시하면 남용으로 간주하여 앱이 일시 중단될 수 있습니다.

추가 참고 자료

• 웹후크 사용에 대한 모범 사례
• GitHub App을 만드는 모범 사례