Рекомендации для интеграторов

Хотите осуществить интеграцию с платформой GitHub? Тогда вы обратились по адресу. Это руководство поможет вам создать приложение, максимально удобное для пользователей и обеспечивающее надежное взаимодействие с API.

Безопасная доставка полезных данных из GitHub

Очень важно защитить полезные данные, передаваемые из GitHub. Хотя личная информация (например, пароли) никогда не передается в полезных данных, нельзя допускать утечки никаких сведений. К конфиденциальным сведениям могут относиться адрес электронной почты участника или имена частных репозиториев.

Существует ряд мер, которыми можно защитить полезные данные, получаемые из GitHub.

Убедитесь в том, что принимающий сервер подключен по HTTPS. По умолчанию GitHub проверяет SSL-сертификаты при доставке полезных данных.
Предоставьте секретный токен, чтобы обеспечить уверенность в том, что полезные данные поступают из GitHub. Применяя секретный маркер, вы гарантируете, что все данные, получаемые сервером, точно поступают из GitHub. В идеале необходимо предоставить отдельный секретный токен для каждого пользователя службы. Если один токен будет скомпрометирован, другие пользователи затронуты не будут.

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

GitHub ожидает, что интеграция ответит в течение 30 секунд после получения полезных данных веб-перехватчика. Если службе требуется больше времени на ответ, GitHub завершает подключение и полезные данные теряются.

Так как невозможно предсказать, насколько быстро ответит служба, вся "реальная работа" должна выполняться в фоновом задании. Примерами библиотек, которые могут выполнять постановку в очередь и обработку фоновых заданий, являются Resque (для Ruby), RQ (для Python) или RabbitMQ (для Java).

Обратите внимание, что даже при выполнении фонового задания GitHub по-прежнему ожидает, что сервер ответит в течение 30 секунд. Ваш сервер должен подтвердить получение полезных данных, отправив какой-либо ответ. Очень важно, чтобы служба проводила все проверки полезных данных как можно скорее, чтобы вы могли точно сообщить, будет ли сервер продолжать выполнение запроса.

Использование соответствующих кодов состояния HTTP при ответе на запросы GitHub

У каждого веб-перехватчика есть собственный раздел "Последние доставки", в котором указывается, было ли развертывание успешным.

Снимок экрана: вкладка "Последние поставки" на странице "Управление веб-перехватчиком".

Для информирования пользователей следует использовать правильные коды состояния HTTP. С помощью такого кода, как 201 или 202, можно подтвердить получение полезных данных, которые не будут обрабатываться (например, доставленных ветвью не по умолчанию). Зарезервируйте код ошибки 500 для неустранимых сбоев.

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

Пользователи могут изучать ответы сервера, отправляемые обратно в GitHub. Сообщения должны быть понятны и информативны.

Снимок экрана: вкладка "Ответ" доставки веб-перехватчика, включая разделы "Заголовки" и "Текст".

Следование всем перенаправлениям, отправляемым API

GitHub явным образом сообщает о перемещении ресурса, предоставляя код состояния перенаправления. Вам необходимо следовать этим перенаправлениям. В каждом ответе о перенаправлении задается заголовок Location с новым универсальным кодом ресурса (URI) для перехода. Если вы получили перенаправление, лучше всего обновить код для использования нового кода URI, чтобы не запрашивать устаревший путь, который, возможно, удален.

Мы предоставили список кодов состояния HTTP для отслеживания перенаправлений при разработке приложения.

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

Ответы API часто содержат данные в виде URL-адресов. Например, при запросе репозитория мы отправляем ключ clone_url с URL-адресом, который можно использовать для клонирования репозитория.

Для стабильной работы приложения не следует пытаться анализировать эти данные или пытаться угадать формат будущих URL-адресов. Если мы решим изменить URL-адрес, работа приложения может нарушиться.

Например, при работе с результатами с разбивкой на страницы кажется логичным, что следует добавлять ?page=<number> в конец URL-адреса. Избегайте такого подхода. Дополнительные сведения о надежном выполнении результатов с разбивкой на страницы см. в разделе Использование разбиения на страницы в REST API.

Проверка типа события и действия перед обработкой события

Существует множество типов событий веб-перехватчиков, и с каждым событием может быть связано несколько действий. По мере расширения набора функций GitHub мы иногда будем добавлять новые типы событий или новые действия к существующим типам событий. Перед обработкой веб-перехватчика приложение должно явным образом проверить тип и действие события. С помощью заголовка запроса X-GitHub-Event можно узнать, какое событие было получено, чтобы обработать его соответствующим образом. Аналогичным образом, у полезных данных есть ключ верхнего уровня action, с помощью которого можно узнать, какое действие было выполнено с соответствующим объектом.

Например, если для веб-перехватчика GitHub настроено действие "Отправить мне все", приложение начнет получать новые типы событий и действия по мере их добавления. Поэтому не рекомендуется использовать предложения типа catch-all else. Рассмотрим следующий пример кода:

# Not recommended: a catch-all else clause
def receive
  event_type = request.headers["X-GitHub-Event"]
  payload    = request.body

  case event_type
  when "repository"
    process_repository(payload)
  when "issues"
    process_issues(payload)
  else
    process_pull_requests
  end
end

В этом примере методы process_repository и process_issues будут вызываться правильно при получении события repository или issues. Однако любой другой тип события приведет к вызову process_pull_requests. По мере добавления новых типов событий это приведет к неправильному поведению, и новые типы событий будут обрабатываться так же, как событие pull_request.

Вместо этого мы рекомендуем явно проверять типы событий и действовать соответствующим образом. В следующем примере кода мы явным образом проверяем событие pull_request, а предложение else просто сообщает, что получен новый тип события:

# Recommended: explicitly check each event type
def receive
  event_type = request.headers["X-GitHub-Event"]
  payload    = JSON.parse(request.body)

  case event_type
  when "repository"
    process_repository(payload)
  when "issues"
    process_issue(payload)
  when "pull_request"
    process_pull_requests(payload)
  else
    puts "Oooh, something new from GitHub: #{event_type}"
  end
end

Так как у каждого события также может быть несколько действий, рекомендуется проверять действия аналогичным образом. Например, у IssuesEvent имеется несколько возможных действий. К ним относятся opened при создании проблемы, closed при закрытии проблемы и assigned при назначении проблемы пользователю.

Помимо добавления типов событий, мы также можем добавлять новые действия для существующий событий. Поэтому при проверке действия события также не рекомендуется использовать предложения типа catch-all else. Вместо этого мы рекомендуем явно проверять действия события, как и в случае с типом события. Пример выглядит очень похоже на то, что было предложено для типов событий выше:

# Recommended: explicitly check each action
def process_issue(payload)
  case payload["action"]
  when "opened"
    process_issue_opened(payload)
  when "assigned"
    process_issue_assigned(payload)
  when "closed"
    process_issue_closed(payload)
  else
    puts "Oooh, something new from GitHub: #{payload["action"]}"
  end
end

В этом примере действие closed проверяется перед вызовом метода process_closed. Все неопознанные действия регистрируются для проверки в будущем.

Ограничения скорости

Ограничение скорости API GitHub гарантирует, что API является быстрым и доступным для всех.

Если достигнуто ограничение скорости, следует прекратить выполнение запросов до истечения времени, указанного в заголовке x-ratelimit-reset . В этом случае интеграция может быть запрещена. Дополнительные сведения см. в разделе Ресурсы в REST API.

Дополнительные ограничения скорости

GitHub также может использовать дополнительные ограничения скорости для обеспечения доступности API. Дополнительные сведения см. в разделе Ресурсы в REST API.

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

Выполняйте запросы с проверкой подлинности или используйте идентификатор клиента и секрет приложения. В отношении запросов без проверки подлинности действуют более строгие дополнительные ограничения скорости.
Выполняйте запросы для одного пользователя или идентификатора клиента последовательно. Не выполняйте запросы для одного пользователя или идентификатора клиента параллельно.
Если вы выполняете много запросов POST, PATCH, PUT или DELETE для одного пользователя или идентификатора клиента, между ними следует делать паузу длительностью по крайней мере в одну секунду.
Если вы ограничены, подождите, прежде чем повторить запрос.
- Если заголовок Retry-After ответа присутствует, повторите запрос по истечении времени, указанного в заголовке. Заголовок Retry-After всегда имеет целочисленное значение, представляющее количество секунд, которое следует подождать, прежде чем выполнять запросы снова. Например, Retry-After: 30 означает, что перед отправкой дополнительных запросов следует подождать 30 секунд.
- Если заголовок x-ratelimit-remaining имеет значение 0, повторите запрос по истечении времени, указанного в заголовке x-ratelimit-reset . Заголовок x-ratelimit-reset всегда будет целым числом, представляющим время сброса текущего окна ограничения скорости в секундах в формате UTC.
- В противном случае дождитесь экспоненциального увеличения времени между повторными попытками и выдаст ошибку после определенного числа повторных попыток.

GitHub оставляет за собой право изменять эти рекомендации по мере необходимости, чтобы обеспечить доступность.

Обработка ошибок API

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

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

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

Рекомендации для интеграторов

В этой статье