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

Введение

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

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

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

• HTTP method (Метод HTTP)
• Путь
• Заголовки
• Типы носителей
• Аутентификация
• Параметры

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

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

Метод HTTP

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

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

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

• GET: используется для получения ресурсов.
• POST: используется для создания ресурсов.
• PATCH: используется для обновления свойств ресурсов.
• PUT: используется для замены ресурсов или коллекций ресурсов.
• DELETE: используется для удаления ресурсов.

Путь

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

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

Заголовки

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

Accept

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

X-GitHub-Api-Version

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

Типы мультимедиа

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

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

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

Существуют пользовательские типы носителей, которые можно использовать с некоторыми конечными точками. Например, REST API для управления фиксациями и [запросами на вытягивание поддерживают типы diffносителей, patchа также sha.](/rest/commits/commits#get-a-commit) Типы fullносителей , raw``textили html используются другими конечными точками.

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

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

Проверка подлинности

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

Параметры

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

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

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

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

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

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

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

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

Параметры запроса позволяют контролировать, какие данные возвращаются для запроса. Обычно эти параметры являются необязательными. Документация для каждой конечной точки REST API GitHub будет описывать все поддерживаемые параметры запроса. Дополнительные сведения см. в разделе 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/REPO-OWNER/REPO-NAME/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/REPO-OWNER/REPO-NAME/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 "http(s)://HOSTNAME/api/v3/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 "http(s)://HOSTNAME/api/v3/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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/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/REPO-OWNER/REPO-NAME/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/REPO-OWNER/REPO-NAME/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 "http(s)://HOSTNAME/api/v3/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 "http(s)://HOSTNAME/api/v3/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.