{"meta":{"title":"REST API 사용에 대한 모범 사례","intro":"GitHub의 API를 사용할 때 이러한 모범 사례를 따르세요.","product":"REST API","breadcrumbs":[{"href":"/ko/rest","title":"REST API"},{"href":"/ko/rest/using-the-rest-api","title":"REST API 사용"},{"href":"/ko/rest/using-the-rest-api/best-practices-for-using-the-rest-api","title":"모범 사례"}],"documentType":"article"},"body":"# REST API 사용에 대한 모범 사례\n\nGitHub의 API를 사용할 때 이러한 모범 사례를 따르세요.\n\n## 폴링을 피하기\n\n데이터에 대한 API를 폴링하는 대신 웹후크 이벤트를 구독해야 합니다. 이렇게 하면 통합이 API 트래픽률 제한 내에서 유지됩니다. 자세한 내용은 [웹후크 설명서](/ko/webhooks)을(를) 참조하세요.\n\n웹후크를 사용할 수 없고 API를 폴링해야 하는 경우 속도 제한을 초과하지 않도록 가능한 한 효율적으로 폴링합니다.\n\n* 고정된 일정에 따라 필요한 만큼만 폴링합니다. 응답에 `x-poll-interval` 헤더가 포함된 경우, 동일한 엔드포인트를 다시 폴링하기 전에 해당 헤더에 지정된 초 수만큼 최소한 기다리세요.\n* 변경되지 않은 데이터가 기본 속도 제한에 포함되지 않도록 인증된 조건부 요청을 수행합니다. 자세한 내용은 [조건부 요청 사용을 참조하세요](#use-conditional-requests).\n* 필요한 데이터만 요청하고 응답을 안정적으로 유지하여 더 많은 설문 조사가 반환 `304 Not Modified`되도록 합니다. 자세한 내용은 [캐시할 수 있는 요청 만들기를 참조하세요](#make-requests-that-can-be-cached).\n\n## 요청 인증하기\n\n인증된 요청은 인증되지 않은 요청보다 기본 속도 제한이 높습니다. 속도 제한을 초과하지 않도록 하려면 인증된 요청을 수행해야 합니다. 자세한 내용은 [REST API에 대한 트래픽률 제한](/ko/rest/using-the-rest-api/rate-limits-for-the-rest-api)을(를) 참조하세요.\n\n## 동시 요청 금지\n\n보조 속도 제한을 초과하지 않도록 하려면 동시에 요청하지 않고 직렬로 요청해야 합니다. 이를 위해 요청에 대한 큐 시스템을 구현할 수 있습니다.\n\n## 변경 요청 간 일시 중지\n\n많은 수의 `POST`, `PATCH`, `PUT` 또는 `DELETE` 요청을 만드는 경우 각 요청 사이에 1초 이상 기다립니다. 이를 통해 보조 속도 제한을 방지할 수 있습니다.\n\n## 속도 제한 오류를 적절하게 처리\n\n트래픽률 제한 오류를 수신하는 경우 다음 지침에 따라 일시적으로 요청을 중지해야 합니다.\n\n* `retry-after` 응답 헤더가 있는 경우 몇 초가 경과할 때까지 요청을 다시 시도하면 안 됩니다.\n* `x-ratelimit-remaining` 헤더가 `0`인 경우 `x-ratelimit-reset` 헤더로 지정된 시간까지 다른 요청을 시도해서는 안 됩니다. 헤더는 `x-ratelimit-reset` UTC Epoch 초 단위입니다.\n* 그렇지 않은 경우 다시 시도하기 전에 1분 이상 기다립니다. 보조 트래픽 속도 제한 때문에 요청이 지속적으로 실패할 경우, 재시도 간격을 기하급수적으로 늘려가며 대기하고, 일정 횟수 이상 재시도해도 실패하면 오류를 발생시킵니다.\n\n트래픽률이 제한된 동안 요청을 계속하면 통합이 금지될 수 있습니다.\n\n## 리다이렉트를 따르세요\n\nREST API는 GitHub 적절한 경우 HTTP 리디렉션을 사용합니다. 사용자는 모든 요청이 리디렉션을 초래할 수 있다고 가정해야 합니다. HTTP 리디렉션을 받는 것은 오류가 아니며 사용자는 해당 리디렉션을 따라야 합니다.\n\n`301` 상태 코드는 영구 리디렉션을 나타냅니다.\n`location` 헤더에 지정된 URL에 대한 요청을 반복해야 합니다. 또한 이후 요청에 이 URL을 사용하도록 코드를 업데이트해야 합니다.\n\n`302` 또는 `307` 상태 코드는 임시 리디렉션을 나타냅니다.\n`location` 헤더에 지정된 URL에 대한 요청을 반복해야 합니다. 그러나 이후 요청에 이 URL을 사용하도록 코드를 업데이트해서는 안 됩니다.\n\n다른 리디렉션 상태 코드는 HTTP 사양에 따라 사용될 수 있습니다.\n\n## URL의 수동 구문 분석 금지\n\n많은 API 엔드포인트는 응답 본문의 필드에 대한 URL 값을 반환합니다. 이러한 URL을 구문 분석하거나 향후 URL의 구조를 예측해서는 안 됩니다. 이로 인해 나중에 URL의 구조가 변경될 경우 GitHub 통합이 중단될 수 있습니다. 대신 필요한 정보가 포함된 필드를 찾아야 합니다. 예를 들어 문제를 만드는 엔드포인트는 `html_url`과 같은 값이 있는 `https://github.com/octocat/Hello-World/issues/1347` 필드와 `number`과 같은 값이 있는 `1347` 필드를 반환합니다. 문제의 수를 알아야 하는 경우 `number` 필드를 구문 분석하는 대신 `html_url` 필드를 사용합니다.\n\n마찬가지로 페이지네이션 쿼리를 수동으로 작성해서는 안 됩니다. 대신 링크 헤더를 사용하여 요청할 수 있는 결과의 페이지를 결정해야 합니다. 자세한 내용은 [REST API에서 페이지 매김 사용](/ko/rest/using-the-rest-api/using-pagination-in-the-rest-api)을(를) 참조하세요.\n\n## 조건부 요청 사용\n\n대부분의 엔드포인트는 `etag` 헤더를 반환하고 많은 엔드포인트는 `last-modified` 헤더를 반환합니다. 이러한 헤더의 값을 사용하여 조건부 `GET` 요청을 수행할 수 있습니다. 응답이 변경되지 않은 경우 `304 Not Modified` 응답을 받게 됩니다. 조건부 요청을 수행했을 때, `304` 응답이 반환되고 `Authorization` 헤더로 올바르게 인증된 상태에서 요청이 이루어진 경우, 해당 요청은 기본 속도 제한에 포함되지 않습니다. 이렇게 하면 각 `304 Not Modified` 응답이 빠르며 속도 제한을 사용하지 않으므로 엔드포인트를 폴링할 때 조건부 요청이 특히 유용합니다.\n\n다음 예제에서는 `YOUR-TOKEN`를 액세스 토큰으로 대체합니다.\n\n`etag`를 사용하여 조건부 요청을 하려면:\n\n1. 요청을 수행하고 응답에서 헤더 값을 `etag` 저장합니다.\n\n   ```shell\n   curl --include --header \"Authorization: Bearer YOUR-TOKEN\" https://api.github.com/repos/octocat/Spoon-Knife/pulls\n   ```\n\n   응답에는 헤더가 포함됩니다.`etag`\n\n   ```text\n   HTTP/2 200\n   etag: \"644b5b0155e6404a9cc4bd9d8b1ae730\"\n   ```\n\n2. 동일한 URL에 대한 다음 요청에서 헤더에 `if-none-match` 저장된 값을 보냅니다.\n\n   ```shell\n   curl --include --header \"Authorization: Bearer YOUR-TOKEN\" --header 'if-none-match: \"644b5b0155e6404a9cc4bd9d8b1ae730\"' https://api.github.com/repos/octocat/Spoon-Knife/pulls\n   ```\n\n   데이터가 변경되지 않은 경우 기본 속도 제한에 포함되지 않는 응답을 받게 `304 Not Modified` 됩니다.\n\n   ```text\n   HTTP/2 304\n   ```\n\n헤더를 `last-modified` 사용할 수도 있습니다. 예를 들어 이전 요청이 `last-modified`의 `Wed, 25 Oct 2023 19:17:59 GMT` 헤더 값을 반환한 경우 이후 요청에서 `if-modified-since` 헤더를 사용할 수 있습니다.\n\n```shell\ncurl --include --header \"Authorization: Bearer YOUR-TOKEN\" --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' https://api.github.com/repos/octocat/Spoon-Knife\n```\n\n특정 엔드포인트에 대한 설명서에 달리 명시되지 않는 한 `POST`, `PUT`, `PATCH`, `DELETE` 등의 안전하지 않은 메서드에 대한 조건부 요청은 지원되지 않습니다.\n\n## 캐시할 수 있는 요청 만들기\n\n조건부 요청은 엔드포인트가 반환 `304 Not Modified`되는 경우에만 시간과 속도 제한을 절약합니다. 엔드포인트는 저장해 둔 `304` 또는 `etag` 값 이후 요청한 표현 형식이 변경되지 않은 경우 `last-modified`를 반환합니다. 날짜와 같은 관련 없는 응답 헤더는 여전히 달라질 수 있습니다.\n`304` 폴링할 때 응답 가능성이 높도록 하려면 요청을 안정적이고 구체적으로 유지합니다.\n\n필요한 데이터만 요청합니다. 더 작고 구체적인 응답은 자주 변경되지 않으므로 더 자주 반환됩니다 `304 Not Modified` . 예를 들어 한 분기에 대한 끌어오기 요청을 확인하려면 모든 끌어오기 요청을 나열하고 결과를 직접 검색하는 대신 해당 분기별로 목록을 필터링합니다.\n`HEAD-OWNER`를 헤드 브랜치를 소유한 계정으로 바꾸세요. 포크에서 생성된 풀 리퀘스트의 경우, 이는 해당 포크를 소유한 계정입니다.\n`BRANCH-NAME` 분기의 이름으로 바꾸고, 다음과 같은 `#``&`특수 문자가 포함된 경우 URL로 인코딩합니다.\n\n```shell\ncurl --include --header \"Authorization: Bearer YOUR-TOKEN\" \"https://api.github.com/repos/octocat/Spoon-Knife/pulls?head=HEAD-OWNER:BRANCH-NAME\"\n```\n\n목록을 페이지 단위로 넘겨 볼 경우 안정적인 정렬 순서를 사용하세요. 항목이 변경 될 때마다 목록의 순서를 다시 지정 하는 등의 `sort=updated`일부 매개 변수입니다. 항목이 새 위치로 이동하면 이전 위치와 새 위치 사이의 항목이 다른 페이지로 이동하므로 이미 가져온 페이지에서 대신 새 데이터를 `304 Not Modified`반환할 수 있습니다. 기본값과 같은 안정적인 순서는 항목을 추가하거나 제거해도 항목을 다른 페이지로 이동할 수 있지만 기존 항목에 대한 업데이트가 목록의 순서를 다시 지정하지 않도록 중지합니다.\n\n동일한 데이터를 폴링할 때마다 동일한 매개 변수를 사용합니다. 다른 페이지 크기, 페이지 번호 또는 필터는 다른 `etag`응답을 생성합니다.\n\n## 오류 무시 금지\n\n반복되는 `4xx` 및 `5xx` 오류 코드를 무시해서는 안 됩니다. 대신 API와 올바르게 상호 작용하고 있는지 확인해야 합니다. 예를 들어 엔드포인트가 문자열을 요청하고 사용자가 숫자 값을 전달하면 유효성 검사 오류가 수신됩니다. 마찬가지로 권한이 없거나 존재하지 않는 엔드포인트에 액세스하려고 하면 `4xx` 오류가 발생합니다.\n\n폴링 중에 리소스가 반복적으로 `404 Not Found` 응답을 반환하는 경우, 폴링할 때마다 해당 리소스를 계속 요청하지 마세요. 먼저 `404`가 인증이나 권한 부여 문제로 인해 발생한 것이 아닌지 확인하세요.\nGitHub\n`404 Not Found` 는 자격 증명이 액세스 권한을 부여하지 않을 때 일부 프라이빗 리소스에 대한 응답 대신 `403 Forbidden` 응답을 반환하므로 `404` 리소스가 항상 없는 것은 아닙니다. 자세한 내용은 [REST API 문제 해결](/ko/rest/using-the-rest-api/troubleshooting-the-rest-api#404-not-found-for-an-existing-resource)을(를) 참조하세요. 자격 증명이 올바른지 확인한 후에는 다시 확인하기 전에 훨씬 더 오래 기다리거나 리소스가 있다고 믿을 만한 이유가 있는 경우에만 다시 확인합니다. 누락된 리소스를 반복적으로 요청하면 속도 제한이 낭비되고 보조 속도 제한을 트리거할 수 있습니다.\n\n반복된 유효성 검사 오류를 의도적으로 무시하면 남용으로 간주하여 앱이 일시 중단될 수 있습니다.\n\n## 추가 참고 자료\n\n* [웹후크 사용에 대한 모범 사례](/ko/webhooks/using-webhooks/best-practices-for-using-webhooks)\n* [GitHub 앱을 만들기 위한 모범 사례](/ko/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)"}