REST API を使用した作業の開始

この記事の例は、https://api.github.com に要求を送信します。 octocorp.ghe.com など、別のドメインで GitHub にアクセスする場合は、API 要求のエンドポイントにそのドメインが反映されます。 (例: https://api.octocorp.ghe.com/)。

既定で、curl は有効な User-Agent ヘッダーを送信します。 ただし、GitHub では、User-Agent ヘッダー値に GitHub Enterprise Cloud ユーザー名またはアプリケーションの名前を使用することをおすすめします。 これにより、問題が発生した場合に GitHub から連絡できます。

要求を認証するには、必要なスコープまたはアクセス許可を持つ認証トークンを提供する必要があります。 トークンを取得するには、いくつかの方法があります。personal access token を作成したり、GitHub App を使ってトークンを生成したり、GitHub Actions ワークフローに組み込まれているGITHUB_TOKEN を使用したりできます。 詳しくは、「REST API に対する認証」を参照してください。

認証トークンを使用する要求の例については、「要求の作成」を参照してください。

このセクションでは、curl を使用して、GitHub REST API に対して認証済み要求を行う方法について説明します。

1. セットアップ

お使いのコンピューター上に curl がインストールされている必要があります。 curl が既にインストールされているかどうかを確認するには、コマンド ラインで curl --version を実行します。

• 出力が curl のバージョンに関する情報であれば、curl がインストールされているということです。
• command not found: curl のようなメッセージが表示された場合は、curl がインストールされていないことを意味します。 curlをダウンロードしてインストールします。 詳しくは、curl のダウンロードに関するページを参照してください。

2. 要求のエンドポイントの選択

1. 要求を行うエンドポイントを選びます。 GitHub Enterprise Cloud の REST API ドキュメント を調べて、GitHub Enterprise Cloud とやりとりするために使用できるエンドポイントを検出できます。

2. エンドポイントの HTTP メソッドとパスを特定します。 これらは要求と共に送信されます。 詳細については、「HTTP メソッド」と「 パス」を参照してください。

   たとえば、"issue の作成" エンドポイント では、HTTP メソッド POST とパス /repos/{owner}/{repo}/issues が使用されます。

3. 必要なパス パラメーターを特定します。 必要なパス パラメーターは、エンドポイントのパスの中かっこ {} で囲まれています。 各パラメーターのプレースホルダーを目的の値に置き換えます。 詳細については、「パス」を参照してください。

   たとえば、"issue の作成" エンドポイント ではパス /repos/{owner}/{repo}/issues が使用され、パス パラメーターは {owner} と {repo} になります。 API 要求でこのパスを使用するには、{repo} を新しい issue を作成するリポジトリの名前に置き換え、{owner} をリポジトリを所有するアカウントの名前に置き換えます。

3. 認証資格情報の作成

要求を認証するためのアクセス トークンを作成します。 トークンを保存し、複数の要求に使用できます。 エンドポイントにアクセスするために必要なスコープまたはアクセス許可をトークンに付与します。 このトークンは要求の Authorization ヘッダーに含めて送信します。 詳細については、認証に関するページをご覧ください。

4. curl 要求を行う

curl コマンドを使用して要求を行います。 詳細については、curl のドキュメントを参照してください。

要求で次のオプションと値を指定します。

• --request または -X の後に、値として HTTP メソッドが続きます。 詳細については、「 HTTP メソッド」を参照してください。

• --url の後に、値として完全なパスが続きます。 完全なパスは、GitHub REST API のベース URL (https://api.github.com または https://api.SUBDOMAIN.ghe.com、GitHub にアクセスしている場所に応じます) と https://api.github.com/PATH のようなエンドポイントのパスを含む URL です。PATH はエンドポイントのパスに置き換えます。 詳細については、「パス」を参照してください。

  クエリ パラメーターを使用するには、パスの末尾に ? を追加してから、クエリ パラメーターの名前と値を parameter_name=value 形式で付加します。 複数のクエリ パラメーターは & で区切ります。 クエリ文字列で配列を送信する場合は、配列の項目ごとに 1 回クエリ パラメーターを使い、クエリ パラメーター名の後に [] を追加します。 たとえば、2 つのリポジトリ ID の配列を指定するには、?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID を使います。 詳細については、「 クエリのパラメーター」を参照してください。 例については、「クエリ パラメーターを使用した要求の例」を参照してください。

• --header または -H:

  • Accept: Accept ヘッダーにメディアの種類を渡します。 Accept ヘッダーに複数のメディアの種類を渡すには、たとえば、Accept: application/vnd.github+json,application/vnd.github.diff というように、メディアの種類をコンマで区切ります。 詳細については、「Accept」と「メディア タイプ」を参照してください。
  • X-GitHub-Api-Version: X-GitHub-Api-Version ヘッダーに API バージョンを渡します。 詳しくは、「X-GitHub-Api-Version」をご覧ください。
  • Authorization:Authorization ヘッダーに認証トークンを渡します。 ほとんどの場合は、Authorization: Bearer または Authorization: token を使用してトークンを渡すことができることにご注意ください。 ただし、JSON Web トークン (JWT) を渡す場合は、Authorization: Bearer を使用する必要があります。 詳細については、認証に関するページをご覧ください。 Authorization ヘッダーを使用する要求の例については、「本文パラメーターを使用した要求の例」を参照してください。

• --data または -d の後に、JSON オブジェクト内の任意の本文パラメーターが続きます。 要求で本文パラメーターを指定する必要がない場合は、このオプションを省略します。 詳しくは、「本文パラメータ」を参照してください。 例については、「本文パラメーターを使用した要求の例」を参照してください。

要求の例

次の要求例では、 "Get Octocat" エンドポイント を使用して、octocat を ASCII アートとして返します。

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"

クエリ パラメーターを使用した要求の例

"パブリック イベントの一覧表示" エンドポイント では、既定で 30 個の issue が返されます。 次の例では、per_page クエリ パラメーターを使用して 30 個ではなく 2 個の issue を返し、page クエリ パラメーターを使用して結果の最初のページのみをフェッチします。

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

本文パラメーターを使用した要求の例

次の例では、"issue の作成" エンドポイントを使用して、octocat/Spoon-Knife リポジトリに新しい issue を作成します。 YOUR-TOKEN を前の手順で作成した認証トークンに置き換えます。

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"
}'

状態コードとヘッダーを表示するには、要求を送信するときに --include または --i オプションを使用します。

たとえば、この要求は、octocat/Spoon-Knife リポジトリの issue の一覧を取得します。

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

この例では、応答コードは 200 で、要求が成功したことを示します。

たとえば、> を使用して、応答をファイルにリダイレクトできます。 次の例では、REPO-OWNER はリポジトリを所有するアカウントの名前に、REPO-NAME はリポジトリの名前に置き換えます。

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 を使用して、各 issue のタイトルと作成者 ID を取得できます。

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

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

前の 2 つのコマンドでは次のようなものが返されます。

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

jq について詳しくは、jq のドキュメントをご覧ください。