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

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

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

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

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

1. セットアップ

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

• 出力が curl のバージョンに関する情報であれば、curl がインストールされているということです。

•         `command not found: curl` のようなメッセージが表示された場合は、`curl` がインストールされていないことを意味します。 
          `curl`をダウンロードしてインストールします。 詳しくは、[curl のダウンロードに関するページ](https://curl.se/download.html)を参照してください。
  

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

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

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

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

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

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

3. 認証資格情報の作成

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

4. curl 要求を行う

          `curl` コマンドを使用して要求を行います。 詳細については、[curl のドキュメント](https://curl.se/docs/manpage.html)を参照してください。

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

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

•         **
          `--url`
          ** の後に、値として完全なパスが続きます。 完全なパスは、GitHub REST API のベース URL (`https://api.github.com`) とエンドポイントのパスを含む URL です(次のように`https://api.github.com/PATH`。 
          `PATH`をエンドポイントのパスに置き換えます。 詳細については、「[Path](#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 オブジェクト内の任意の本文パラメーターが続きます。 要求で本文パラメーターを指定する必要がない場合は、このオプションを省略します。 詳細については、「[本文パラメーター](#body-parameters)」を参照してください。 例については、「[本文パラメーターを使用した要求の例](#example-request-using-body-parameters-1)」を参照してください。
  

要求の例

次の要求例では、 "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"

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

          ["パブリック イベントの一覧表示" エンドポイント](/rest/activity/events#list-public-events) では、既定で 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

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

次の例では「イシューの作成」エンドポイントを使用して、指定されたリポジトリに新しいイシューを作成します。 YOUR-TOKENは、前の手順で作成した認証トークンに置き換えます。

          fine-grained personal access tokenを使用している場合は、`octocat/Spoon-Knife`を、自分が所有しているリポジトリ、または自分が所属する組織が所有するリポジトリに置き換える必要があります。 お使いのトークンは、リポジトリにアクセスできる必要があり、リポジトリの issue に対する読み取りと書き込みのアクセス許可が必要です。 詳しくは、「[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-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-Knifea の問題の一覧を取得します。

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 のドキュメントをご覧ください。