Начало работы с REST API

Введение

В этой статье описывается, как использовать GitHub REST API с GitHub CLI, curlили JavaScript. Краткое руководство см . в разделе AUTOTITLE.

Сведения о запросах к REST API

В этом разделе описываются элементы, составляющие запрос API:

•         [Метод HTTP](#http-method)
  

•         [Путь](#path)
  

•         [Заголовки](#headers)
  

•         [Типы носителей](#media-types)
  

•         [Аутентификация](#authentication)
  

•         [Параметры](#parameters)
  

Каждый запрос к REST API включает метод HTTP и путь. В зависимости от конечной точки REST API может потребоваться также указать заголовки запросов, сведения о проверке подлинности, параметры запроса или параметры текста.

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

HTTP method (Метод HTTP)

Метод HTTP конечной точки определяет тип действия, выполняемого в заданном ресурсе. Некоторые распространенные методы HTTP: GET, POST``DELETEи PATCH. Справочная документация по REST API предоставляет метод HTTP для каждой конечной точки.

Например, http-метод для конечной точкиGET"Проблемы с репозиторием списка".

По возможности GitHub REST API стремится использовать подходящий HTTP-метод для каждого действия.

•         `GET`: используется для получения ресурсов.
  

•         `POST`: используется для создания ресурсов.
  

•         `PATCH`: используется для обновления свойств ресурсов.
  

•         `PUT`: используется для замены ресурсов или коллекций ресурсов.
  

•         `DELETE`: используется для удаления ресурсов.
  

Путь

Каждая конечная точка имеет путь. Справочная документация по REST API предоставляет путь для каждой конечной точки. Например, путь к конечной точке /repos/{owner}/{repo}/issues"Проблемы с репозиторием списка".

Фигурные скобки {} в пути указывают параметры пути, которые необходимо указать. Параметры пути изменяют путь конечной точки и требуются в запросе. Например, параметры пути для конечной точки "Проблемы с репозиторием списка" и {owner}``{repo} . Чтобы использовать этот путь в запросе API, замените {repo} на имя репозитория, в котором вы хотите запросить список проблем, и замените {owner} именем учетной записи, принадлежащей репозиторию.

Заголовки

Заголовки предоставляют дополнительные сведения о запросе и требуемом ответе. Ниже приведены примеры заголовков, которые вы можете использовать в запросах к GitHub REST API. Пример запроса, использующего заголовки, см. в разделе "Создание запроса".

Accept

Большинство конечных точек GitHub REST API указывают, что нужно передавать Accept заголовок со значением application/vnd.github+json. Значение заголовка Accept — тип носителя. Дополнительные сведения о типах носителей см. в разделе "Типы носителей".

X-GitHub-Api-Version

Этот заголовок следует использовать для указания версии REST API, используемой для запроса. Дополнительные сведения см. в разделе Версии API.

User-Agent

Все запросы API должны содержать допустимый User-Agent заголовок. Заголовок User-Agent определяет пользователя или приложение, выполняющее запрос.

Ниже приведен пример User-Agent для приложения с именем Awesome-Octocat-App:

User-Agent: Awesome-Octocat-App

Запросы без заголовка User-Agent отклоняются. Если указать недопустимый User-Agent заголовок, вы получите 403 Forbidden ответ.

Типы носителей

Можно указать один или несколько типов носителей, добавив их в Accept заголовок запроса. Дополнительные сведения о заголовке Accept см. в разделеAccept .

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

Наиболее распространённые типы медиа, поддерживаемые GitHub REST API, — это application/vnd.github+json и application/json.

Существуют пользовательские типы носителей, которые можно использовать с некоторыми конечными точками. Например, REST API для управления фиксациями и Типы fullносителей , raw``textили html используются другими конечными точками.

Все пользовательские типы GitHub медиа выглядят так: application/vnd.github.PARAM+json, где PARAM — название типа медиа. Например, чтобы указать raw тип носителя, следует использовать application/vnd.github.raw+json.

Пример запроса, использующего типы носителей, см. в разделе "Создание запроса".

Аутентификация

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

Параметры

Многие методы API требуют или позволяют отправлять дополнительные сведения в параметрах запроса. Существует несколько различных типов параметров: параметры пути, параметры тела и параметры запроса.

Параметры пути

Параметры пути изменяют путь конечной точки. Эти параметры необходимы в запросе. Дополнительные сведения см. в разделе "Путь".

Параметры запроса

Параметры запроса позволяют передавать дополнительные данные в API. Эти параметры могут быть необязательными или обязательными в зависимости от конечной точки. Например, параметр body может позволить указать заголовок проблемы при создании новой проблемы или указать определенные параметры при включении или отключении функции. Документация по каждой GitHub конечной точке REST API описывает поддерживаемые им параметры тела. Дополнительные сведения см. в разделе AUTOTITLE.

Например, для конечной точки "Создание проблемы" требуется указать название новой проблемы в запросе. Кроме того, вы можете дополнительно указать другие сведения, например текст, помещенный в текст проблемы, пользователи могут назначить новую проблему или метки для применения к новой проблеме. Пример запроса, использующего параметры текста, см. в разделе "Создание запроса".

Для передачи параметров тела необходимо пройти проверку подлинности запроса. Дополнительные сведения см. в разделе Authenticate to the Speech API (Аутентификация в API речи).

Параметры запроса

Параметры запроса позволяют контролировать, какие данные возвращаются для запроса. Обычно эти параметры являются необязательными. Документация для каждой GitHub конечной точки REST API описывает любые поддерживаемые ими параметры запроса. Дополнительные сведения см. в разделе AUTOTITLE.

Например, конечная точка "Список общедоступных событий" возвращает тридцать проблем по умолчанию. Для возврата двух проблем вместо 30 можно использовать per_page параметр запроса. Параметр запроса можно использовать page для получения только первой страницы результатов. Пример запроса, использующего параметры запроса, см. в разделе "Создание запроса".

Выполнение запроса

gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

Использование ответа

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

Сведения о коде ответа и заголовках

Каждый запрос возвращает код состояния HTTP, указывающий на успешность ответа. Дополнительные сведения о кодах ответов см. в документации по кодам состояния ответов MDN HTTP.

Кроме того, ответ будет содержать заголовки, которые предоставляют дополнительные сведения об ответе. Заголовки, которые начинаются с X- .x-GitHub Например, заголовки x-ratelimit-remaining и x-ratelimit-reset сообщают, сколько запросов можно выполнить за период времени.

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/octocat/Spoon-Knife/issues \
-F per_page=2 --include

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Cache-Control: private, max-age=60, s-maxage=60
Content-Security-Policy: default-src 'none'
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Aug 2022 19:56:41 GMT
Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418"
Link: <https://api.github.com/repositories/1300192/issues?per_page=1&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=1&page=14817>; rel="last"
Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin
Server: GitHub.com
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Vary: Accept, Authorization, Cookie, Accept-Encoding, Accept, X-Requested-With
X-Accepted-Oauth-Scopes: repo
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Github-Api-Version-Selected: 2022-08-09
X-Github-Media-Type: github.v3; format=json
X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479
X-Oauth-Client-Id: 178c6fc778ccc68e1d6a
X-Oauth-Scopes: gist, read:org, repo, workflow
X-Ratelimit-Limit: 15000
X-Ratelimit-Remaining: 14996
X-Ratelimit-Reset: 1659645499
X-Ratelimit-Resource: core
X-Ratelimit-Used: 4
X-Xss-Protection: 0

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

Сведения о тексте ответа

Многие конечные точки возвращают текст ответа. Если не указано иное, текст ответа имеет формат JSON. Пустые поля включаются как null, а не пропускаются. Все метки времени возвращаются в формате UTC, формат ISO 8601: YYYY-MM-DDTHH:MM:SSZ

В отличие от API GraphQL, в котором вы указываете желаемую информацию, REST API обычно возвращает больше информации, чем требуется. При необходимости можно проанализировать ответ, чтобы извлечь определенные данные.

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

Подробные и суммарные представления

Ответ может включать все атрибуты ресурса или только подмножество атрибутов в зависимости от того, извлекаете отдельный ресурс или список ресурсов.

• При получении отдельного ресурса _, например определенного _репозитория, ответ обычно будет включать все атрибуты для этого ресурса. Это "подробное" представление ресурса.
• При получении списка ресурсов, таких как список нескольких репозиториев, ответ будет включать только подмножество атрибутов для каждого ресурса. Это "сводное" представление ресурса.

Обратите внимание, что авторизация иногда влияет на объем сведений, включенных в представление.

Причина в том, что некоторые атрибуты вычислительно затратны для предоставления API, поэтому GitHub эти атрибуты исключаются из сводного представления. Чтобы получить эти атрибуты, можно получить подробное представление.

В документации приводится пример ответа для каждого метода API. В примере ответа показаны все атрибуты, возвращаемые этим методом.

Гиперсреда

Любой ресурс может иметь одно или несколько свойств *_url, содержащих ссылки на другие ресурсы. Они предназначены для предоставления явных URL-адресов, чтобы соответствующим клиентам API не приходилось формировать URL-адреса самостоятельно. Настоятельно рекомендуется, чтобы клиенты API использовали эти свойства. Так разработчикам будет проще обновлять API в будущем. Все URL-адреса должны соответствовать шаблонам URI RFC 6570.

Затем можно расширить эти шаблоны, например, с помощью пакета uri_template:

>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"

>> tmpl.expand all: 1
=> "/notifications?all=1"

>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"

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

REST API ограничивает количество запросов, GitHub которые вы можете сделать за определённый промежуток времени. Для получения дополнительной информации о тарифных лимитах и о том, как проверить текущий статус лимита ставки, смотрите AUTOTITLE.

Следующие шаги

В этой статье показано, как перечислить и создать проблемы в репозитории. Попрактикуйтесь, прокомментировав проблему, изменив заголовок проблемы или закрыв проблему. Дополнительные сведения см. в разделе "Создание комментария проблемы" и конечной точки "Обновление проблемы".

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