{"meta":{"title":"Рекомендации по использованию REST API","intro":"Следуйте этим лучшим практикам при использовании GitHubAPI 's.","product":"REST API","breadcrumbs":[{"href":"/ru/rest","title":"REST API"},{"href":"/ru/rest/using-the-rest-api","title":"Использование REST API"},{"href":"/ru/rest/using-the-rest-api/best-practices-for-using-the-rest-api","title":"Рекомендации"}],"documentType":"article"},"body":"# Рекомендации по использованию REST API\n\nСледуйте этим лучшим практикам при использовании GitHubAPI 's.\n\n## Избегайте опроса\n\nВы должны подписаться на события веб-перехватчика вместо опроса API для данных. Это поможет вашей интеграции оставаться в пределах ограничения скорости API. Дополнительные сведения см. в разделе [Документация по веб-перехватчикам](/ru/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](/ru/rest/using-the-rest-api/rate-limits-for-the-rest-api).\n\n## Избегайте одновременных запросов\n\nЧтобы избежать превышения ограничений вторичной частоты, следует выполнять последовательные запросы вместо параллельного выполнения. Для этого можно реализовать систему очередей для запросов.\n\n## Приостановка между мутативными запросами\n\nЕсли вы делаете большое количество `POST`, `PATCH``PUT`или `DELETE` запросы, подождите по крайней мере одну секунду между каждым запросом. Это поможет избежать дополнительных ограничений скорости.\n\n## Обработка ошибок ограничения скорости соответствующим образом\n\nЕсли вы получаете ошибку ограничения скорости, следует временно прекратить выполнение запросов в соответствии с этими рекомендациями:\n\n* `retry-after` Если заголовок ответа присутствует, не следует повторять запрос до тех пор, пока не истекло много секунд.\n* Если заголовок `x-ratelimit-remaining` имеет значение `0`, вы не должны выполнять другой запрос до тех пор, пока время, указанное заголовком `x-ratelimit-reset` . Заголовок `x-ratelimit-reset` находится в секундах эпохи UTC.\n* В противном случае дождитесь хотя бы одной минуты, прежде чем повторить попытку. Если запрос продолжает завершаться ошибкой из-за дополнительного ограничения скорости, подождите экспоненциально увеличивающееся время между повторными попытками и вызовите ошибку после определенного числа повторных попыток.\n\nПродолжая делать запросы во время ограничения скорости, может привести к запрету интеграции.\n\n## Следуйте перенаправлениям\n\nGitHub REST API использует HTTP-перенаправление, где это уместно. Следует предположить, что любой запрос может привести к перенаправлению. Получение перенаправления HTTP не является ошибкой, и вы должны следовать перенаправлению.\n\nКод `301` состояния указывает на постоянное перенаправление. Необходимо повторить запрос к URL-адресу, указанному заголовком `location` . Кроме того, необходимо обновить код, чтобы использовать этот URL-адрес для будущих запросов.\n\n`302` Код `307` состояния или указывает временное перенаправление. Необходимо повторить запрос к URL-адресу, указанному заголовком `location` . Однако не следует обновлять код, чтобы использовать этот URL-адрес для будущих запросов.\n\nДругие коды состояния перенаправления могут использоваться в соответствии с спецификациями HTTP.\n\n## Не анализируйте URL-адреса вручную\n\nМногие конечные точки API возвращают значения URL-адреса для полей в тексте ответа. Не следует пытаться проанализировать эти URL-адреса или предсказать структуру будущих URL-адресов. Это может привести к нарушению вашей интеграции, если GitHub в будущем изменится структура URL. Вместо этого следует искать поле, содержащее необходимые сведения. Например, конечная точка для создания проблемы возвращает `html_url` поле со значением, как `https://github.com/octocat/Hello-World/issues/1347` и `number` поле со значением, например `1347`. Если вам нужно знать количество проблем, используйте `number` поле вместо синтаксического анализа `html_url` поля.\n\nАналогичным образом не следует пытаться вручную создавать запросы на страницы. Вместо этого следует использовать заголовки ссылок, чтобы определить, какие страницы результатов можно запросить. Дополнительные сведения см. в разделе [Использование разбиения на страницы в REST API](/ru/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` значения; несвязанные заголовки ответа, такие как дата, по-прежнему могут отличаться. Чтобы сделать `304` ответы более вероятными при опросе, сохраняйте свои запросы стабильными и конкретными.\n\nЗапрашивайте только необходимые данные. Меньший, более конкретный ответ меняется реже, поэтому он возвращается `304 Not Modified` чаще. Например, чтобы проверить запросы на вытягивание для одной ветви, отфильтруйте список по этой ветви вместо перечисления каждого запроса на вытягивание и поиска результатов самостоятельно. Замените `HEAD-OWNER` учетной записью, которая владеет головной ветвью; для запроса на вытягивание из вилки это учетная запись, которая владеет вилкой. Замените `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](/ru/rest/using-the-rest-api/troubleshooting-the-rest-api#404-not-found-for-an-existing-resource). Убедившись, что ваши учетные данные верны, подождите гораздо дольше, прежде чем снова проверить или повторите проверку только в том случае, если у вас есть причина поверить, что ресурс существует. Многократно запрашивая отсутствующий ресурс, выпустите ограничение скорости и может активировать дополнительный предел скорости.\n\nНамеренное игнорирование повторяющихся ошибок проверки может привести к временному блокированию приложения из-за нарушения.\n\n## Дополнительные материалы\n\n* [Рекомендации по использованию веб-перехватчиков](/ru/webhooks/using-webhooks/best-practices-for-using-webhooks)\n* [Лучшие практики создания приложения на GitHub](/ru/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)"}