Рекомендации по использованию REST API

Избегайте опроса

Вы должны подписаться на события веб-перехватчика вместо опроса API для данных. Это поможет вашей интеграции оставаться в пределах ограничения скорости API. Дополнительные сведения см. в разделе Документация по веб-перехватчикам.

Создание аутентифицированных запросов

Запросы, прошедшие проверку подлинности, имеют более высокий уровень первичной частоты, чем запросы без проверки подлинности. Чтобы избежать превышения предела скорости, следует выполнять прошедшие проверку подлинности запросы. Дополнительные сведения см. в разделе Ограничения скорости для REST API.

Избегайте одновременных запросов

Чтобы избежать превышения ограничений вторичной частоты, следует выполнять последовательные запросы вместо параллельного выполнения. Для этого можно реализовать систему очередей для запросов.

Приостановка между мутативными запросами

Если вы делаете большое количество POST, PATCH``PUTили DELETE запросы, подождите по крайней мере одну секунду между каждым запросом. Это поможет избежать дополнительных ограничений скорости.

Обработка ошибок ограничения скорости соответствующим образом

Если вы получаете ошибку ограничения скорости, следует временно прекратить выполнение запросов в соответствии с этими рекомендациями:

• retry-after Если заголовок ответа присутствует, не следует повторять запрос до тех пор, пока не истекло много секунд.
• Если заголовок x-ratelimit-remaining имеет значение 0, вы не должны выполнять другой запрос до тех пор, пока время, указанное заголовком x-ratelimit-reset . Заголовок x-ratelimit-reset находится в секундах эпохи UTC.
• В противном случае дождитесь хотя бы одной минуты, прежде чем повторить попытку. Если запрос продолжает завершаться ошибкой из-за дополнительного ограничения скорости, подождите экспоненциально увеличивающееся время между повторными попытками и вызовите ошибку после определенного числа повторных попыток.

Продолжая делать запросы во время ограничения скорости, может привести к запрету интеграции.

Следуйте перенаправлениям

REST API GitHub Enterprise Server использует перенаправление HTTP, насколько это возможно. Следует предположить, что любой запрос может привести к перенаправлению. Получение перенаправления HTTP не является ошибкой, и вы должны следовать перенаправлению.

Код 301 состояния указывает на постоянное перенаправление. Необходимо повторить запрос к URL-адресу, указанному заголовком location . Кроме того, необходимо обновить код, чтобы использовать этот URL-адрес для будущих запросов.

307 Код 302 состояния или указывает временное перенаправление. Необходимо повторить запрос к URL-адресу, указанному заголовком location . Однако не следует обновлять код, чтобы использовать этот URL-адрес для будущих запросов.

Другие коды состояния перенаправления могут использоваться в соответствии с спецификациями HTTP.

Не анализируйте URL-адреса вручную

Многие конечные точки API возвращают значения URL-адреса для полей в тексте ответа. Не следует пытаться проанализировать эти URL-адреса или предсказать структуру будущих URL-адресов. Это может привести к разрыву интеграции, если GitHub изменяет структуру URL-адреса в будущем. Вместо этого следует искать поле, содержащее необходимые сведения. Например, конечная точка для создания проблемы возвращает html_url поле со значением, как https://github.com/octocat/Hello-World/issues/1347 и number поле со значением, например 1347. Если вам нужно знать количество проблем, используйте number поле вместо синтаксического анализа html_url поля.

Аналогичным образом не следует пытаться вручную создавать запросы на страницы. Вместо этого следует использовать заголовки ссылок, чтобы определить, какие страницы результатов можно запросить. Дополнительные сведения см. в разделе Использование разбиения на страницы в REST API.

При необходимости используйте условные запросы

Большинство конечных точек возвращают etag заголовок, и многие конечные точки возвращают last-modified заголовок. Значения этих заголовков можно использовать для выполнения условных запросов. Если ответ не изменился, вы получите 304 Not Modified ответ. Выполнение условного запроса не учитывается в отношении основного ограничения скорости, если 304 возвращается ответ.

Например, если предыдущий запрос вернул etag значение 644b5b0155e6404a9cc4bd9d8b1ae730заголовка, можно использовать if-none-match заголовок в следующем запросе:

curl http(s)://HOSTNAME/api/v3/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'

Например, если предыдущий last-modified запрос вернул значение Wed, 25 Oct 2023 19:17:59 GMTзаголовка, можно использовать if-modified-since заголовок в следующем запросе:

curl http(s)://HOSTNAME/api/v3/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'

Не игнорируйте ошибки

Не следует игнорировать повторяющиеся 4xx и 5xx коды ошибок. Вместо этого необходимо убедиться, что вы правильно взаимодействуете с API. Например, если конечная точка запрашивает строку и передаете его числовое значение, вы получите ошибку проверки. Аналогичным образом, попытка доступа к неавторизованной или несуществующей конечной точке приведет к ошибке 4xx.

Намеренное игнорирование повторяющихся ошибок проверки может привести к временному блокированию приложения из-за нарушения.

Дополнительные материалы

• "Рекомендации по использованию веб-перехватчиков"
• "Рекомендации по созданию приложения GitHub"