Skip to main content

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

GitHub REST API の使用方法について学習します。

はじめに

この記事では、GitHub CLI、curl、またはJavaScriptを使う GitHub REST API の使用方法について説明します。 クイックスタート ガイドについては、「GitHub REST API のクイックスタート」をご覧ください。

REST API への要求について

このセクションでは、API 要求を構成する要素について説明します。

REST API に対するすべての要求には、HTTP メソッドとパスが含まれます。 REST API エンドポイントによっては、要求ヘッダー、認証情報、クエリ パラメーター、または本文パラメーターも指定する必要があります。

REST API リファレンス ドキュメントでは、すべてのエンドポイントの HTTP メソッド、パス、およびパラメーターについて説明します。 また、各エンドポイントの要求と応答の例も表示されます。 詳しくは、REST のリファレンス ドキュメントをご覧ください。

HTTP メソッド

エンドポイントの HTTP メソッドは、特定のリソースに対して実行するアクションの種類を定義します。 一般的な HTTP メソッドには GETPOSTDELETEPATCH があります。 REST API リファレンス ドキュメントには、すべてのエンドポイントの HTTP メソッドが記載されています。

たとえば、「リポジトリの issue の一覧表示」エンドポイントの HTTP メソッドは GET です。

GitHub Enterprise Server REST API では、可能な限り、各アクションに適した HTTP メソッドを使用しようとします。

  • GET: リソースを取得するために使用します。
  • POST: リソースを作成するために使用します。
  • PATCH: リソースのプロパティを更新するために使用されます。
  • PUT: リソースまたはリソースのコレクションを置き換えるために使用します。
  • DELETE: リソースを削除するために使用します。

Path

各エンドポイントにはパスがあります。 REST API リファレンス ドキュメントには、すべてのエンドポイントのパスが記載されています。 たとえば、"リポジトリの issue の一覧表示" エンドポイント/repos/{owner}/{repo}/issues となります。

パスの中かっこ {} は、指定する必要があるパス パラメーターを示します。 パス パラメーターはエンドポイント パスを変更し、要求に必要です。 たとえば、"リポジトリの issues の一覧表示" エンドポイントのパス パラメーターは {owner}{repo} になります。 API 要求でこのパスを使用するには、{repo} を問題の一覧を要求するリポジトリの名前に置き換え、{owner} をリポジトリを所有するアカウントの名前に置き換えます。

ヘッダー

ヘッダーは、要求と必要な応答に関する追加情報を提供します。 GitHub REST API への要求で使用できるヘッダーの例を次に示します。 ヘッダーを使用する要求の例については、「要求の作成」を参照してください。

Accept

ほとんどの GitHub REST API エンドポイントでは、値が application/vnd.github+json のヘッダー Accept を渡す必要があることを指定しています。 Accept ヘッダーの値はメディアの種類です。 メディアの種類の詳細については、「メディアの種類」をご覧ください。

X-GitHub-Api-Version

このヘッダーを使用して、要求に使用する REST API のバージョンを指定する必要があります。 詳しくは、「API のバージョン」を参照してください。

メディアの種類

1 つ以上のメディアの種類を指定するには、それらを要求のAccept ヘッダーに 追加します。 Accept ヘッダーの詳細については、「Accept」を参照してください。

メディアの種類は、API から使用するデータの形式を指定します。 メディアの種類はリソースに固有であるため、個別に変更したり、他のリソースではサポートされていない形式をサポートしたりできます。 各 GitHub REST API エンドポイントのドキュメントでは、サポートされているメディアの種類について説明します。 詳しくは、「GitHub REST API に関するドキュメント」をご覧ください。

GitHub REST API でサポートされる最も一般的なメディアの種類は application/vnd.github+jsonapplication/json です。

一部のエンドポイントで使用できるカスタム メディアの種類があります。 たとえば、コミットpull request を管理する REST API では、diffpatchsha というメディアの種類がサポートされます。 fullrawtexthtml というメディアの種類は、他のエンドポイントで使用されます。

GitHub Enterprise Server のすべてのカスタム メディアの種類は次のようになります。application/vnd.github.PARAM+jsonPARAM がメディアの種類の名前です。 たとえば、raw メディアの種類を指定するには、application/vnd.github.raw+json を使用します。

メディアの種類を使用する要求の例については、「要求の作成」を参照してください。

認証

多くのエンドポイント操作では、認証が必要であるか、認証されている場合は追加情報が返されます。 さらに、認証されている場合は 1 時間あたりの要求を増やすことができます。

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

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

: トークンを作成しない場合は、GitHub CLI を使用できます。 GitHub CLI は認証を処理し、アカウントのセキュリティを維持するのに役立ちます。 詳しくは、このページのGitHub CLI バージョンを参照してください。

警告: パスワードやその他の機密性の高い資格情報を扱うのと同じ方法でアクセス トークンを扱います。 詳しくは、「API 資格情報をセキュリティで保護する」を参照してください。

一部の REST API エンドポイントには認証なしでアクセスできますが、GitHub CLI では、api サブコマンドを使用して API 要求を行う前に認証する必要があります。 auth login サブコマンドを使用して、 に対する認証を行います。 詳細については、「要求の作成」を参照してください。

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

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

警告: パスワードやその他の機密性の高い資格情報を扱うのと同じ方法でアクセス トークンを扱います。 詳しくは、「API 資格情報をセキュリティで保護する」を参照してください。

パラメーター

多くの API メソッドでは、要求のパラメーターに追加情報を送信する必要があります。 パラメーターには、パス パラメーター、本文パラメーター、クエリ パラメーターなど、いくつかの種類があります。

パス パラメーター

パス パラメーターではエンドポイントパスを変更します。 これらは要求に必須です。 詳細については、「パス」を参照してください。

本文パラメータ

本文パラメーターを使用すると、API に追加のデータを渡すことができます。 これらのパラメーターは、エンドポイントに応じて省略可能または必須にすることができます。 たとえば、本文パラメーターを使用すると、新しい問題を作成するときに問題のタイトルを指定したり、機能を有効または無効にするときに特定の設定を指定したりできます。 各 GitHub REST API エンドポイントのドキュメントでは、サポートされている本文パラメーターについて説明します。 詳しくは、「GitHub REST API に関するドキュメント」をご覧ください。

たとえば、"issue の作成" エンドポイント では、要求で新しい issue のタイトルを指定する必要があります。 また、必要に応じて issue 本文に入力するテキスト、新しい issue に割り当てるユーザー、新しい issue に適用するラベルなど、その他の情報を指定することもできます。 本文パラメーターを使用する要求の例については、「要求の作成」を参照してください。

本文パラメーターを渡すには、要求を認証する必要があります。 詳しくは、「認証」を参照してください。

クエリ パラメーター

クエリ パラメーターを使用すると、要求に対して返されるデータを制御できます。 これらのパラメーターは通常省略可能です。 各 GitHub REST API エンドポイントのドキュメントでは、サポートされているクエリ パラメーターについて説明します。 詳しくは、「GitHub REST API に関するドキュメント」をご覧ください。

たとえば、"パブリック イベントの一覧表示" エンドポイント では、既定で 30 個の issue が返されます。 per_page クエリ パラメーターを使用すると、30 個ではなく 2 個の issue を返すことができます。 page クエリ パラメーターを使用して、結果の最初のページのみをフェッチできます。 クエリ パラメーターを使用する要求の例については、「要求の作成」を参照してください。

要求を行う

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

1. セットアップ

macOS、Windows、または Linux に GitHub CLI をインストールします。 詳細については、GitHub CLI リポジトリ内でのインストールを参照してください。

2. 認証

  1. ターミナルからこのコマンドを実行して、GitHub で認証します。HOSTNAME は お使いの GitHub Enterprise Server インスタンス の名前に置き換えます。 たとえば、octo-inc.ghe.com です。

    Shell
    gh auth login --hostname HOSTNAME
    

    --scopes オプションを使用して、必要なスコープを指定できます。 作成したトークンで認証する場合は、--with-token オプションを使用できます。 詳しくは、GitHub CLIauth login のドキュメントを参照してください。

  2. 画面の指示に従います。

    GitHub CLI は、Git 操作の優先プロトコルとして HTTPS を選択すると自動的に Git 資格情報を格納し、GitHub 資格情報で Git に対して認証するかどうかを尋ねるプロンプトに対して "はい" と答えます。 これは、別の資格情報マネージャーを設定したり、SSH を使用したりすることなく、git pushgit pull などの Git を使用できるので便利です。

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

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

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

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

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

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

4. GitHub CLI で要求を行う

GitHub CLI api サブコマンドを使用して API 要求を行います。 詳しくは、GitHub CLIapi のドキュメントを参照してください。

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

  • --method の後に HTTP メソッドとエンドポイントのパスが続きます。 詳細については、「HTTP メソッド」と「 パス」を参照してください。

  • --header:

    • 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」をご覧ください。
  • -f または -F の後に、key=value 形式の任意の本文パラメーターまたはクエリ パラメーターが続きます。 この -F オプションを使用して、数値、ブール値、または null のパラメーターを渡します。 文字列パラメーターを渡すには、-f オプションを使用します。

    一部のエンドポイントでは、配列のクエリ パラメーターが使われます。 クエリ文字列で配列を送信するには、配列の項目ごとに 1 回クエリ パラメーターを使い、クエリ パラメーター名の後に [] を追加します。 たとえば、2 つのリポジトリ ID の配列を指定するには、-f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID を使います。

    要求で本文パラメーターまたはクエリ パラメーターを指定する必要がない場合は、このオプションを省略します。 詳細については、「本文パラメーター」と「クエリ パラメーター」を参照してください。 例については、「本文パラメーターを使用した要求の例」と「クエリ パラメーターを使用した要求の例」を参照してください。

要求の例

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

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

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

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

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

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

次の例では、"issue の作成" エンドポイント を使用して、指定したリポジトリに新しい issue を作成します。REPO-NAME は新しい issue を作成するリポジトリの名前に置き換え、REPO-OWNER はリポジトリを所有するアカウントの名前に置き換えます。応答で issue の html_url を見つけ、ブラウザーの issue に移動します。

Shell
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 を使用して、GitHub REST API に対して認証済み要求を行う方法について説明します。

1. セットアップ

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

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

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

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

  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 (https://api.github.com) のベース URL と http(s)://HOSTNAME/api/v3/PATH のようなエンドポイントのパスを含む URL です。HOSTNAME は お使いの GitHub Enterprise Server インスタンス の名前に置き換えます。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 アートとして返します。

Shell
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 クエリ パラメーターを使用して結果の最初のページのみをフェッチします。

Shell
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

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

次の例では、"issue の作成" エンドポイントを使用して、指定したリポジトリに新しい issue を作成します。HOSTNAME は お使いの GitHub Enterprise Server インスタンス の名前に置き換えます。 REPO-NAME を新しい issue を作成するリポジトリの名前に置き換え、REPO-OWNER をリポジトリを所有するアカウントの名前に置き換えます。 YOUR-TOKEN を前の手順で作成した認証トークンに置き換えます。

: fine-grained personal access token を使用している場合は、REPO-OWNERREPO-NAME を、自分が所有している、または自分がメンバーである organization によって所有されているリポジトリに置き換える必要があります。 お使いのトークンは、リポジトリにアクセスできる必要があり、リポジトリの issue に対する読み取りと書き込みのアクセス許可が必要です。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。

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

このセクションでは、JavaScript と Octokit.js を使用して GitHub REST API に要求する方法について説明します。 さらに詳しいガイドについては、「REST API と JavaScript を使用したスクリプト」をご覧ください。

1. セットアップ

次の例に示す Octokit.js ライブラリを使用するには、octokit をインストールする必要があります。

  • octokitをインストールする。 たとえば、「 npm install octokit 」のように入力します。 octokit をインストールまたは読み込むための他の方法については、Octokit.js の README を参照してください。

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

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

  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. Octokit.js で要求を行う

  1. スクリプトで octokit をインポートします。 たとえば、「 import { Octokit } from "octokit"; 」のように入力します。 その他の octokit のインポート方法については、Octokit.js の README を参照してください。

  2. トークンを使用して Octokit のインスタンスを作成します。ベース URL を http(s)://HOSTNAME/api/v3 に設定します。 HOSTNAME を お使いの GitHub Enterprise Server インスタンス の名前に置き換えます。 YOUR-TOKEN をお使いのトークンに置き換えます。

    JavaScript
    const octokit = new Octokit({ 
      baseUrl: "http(s)://HOSTNAME/api/v3",
      auth: 'YOUR-TOKEN'
    });
    
  3. octokit.request を使用して、要求を実行します。

    • HTTP メソッドとパスをrequest メソッドの最初の引数として送信します。 詳細については、「HTTP メソッド」と「 パス」を参照してください。
    • オブジェクト内のすべてのパス、クエリ、および本文パラメーターを request メソッドの 2 番目の引数として指定します。 詳しくは、「パラメーター」をご覧ください。

    次の要求例では、HTTP メソッドは POST、パスは /repos/{owner}/{repo}/issues、パス パラメーターは owner: "REPO-OWNER"repo: "REPO-NAME"、本文パラメーターは title: "Created with the REST API"body: "This is a test issue created by the REST API" です。REPO-OWNER はリポジトリを所有するアカウントの名前に、REPO-NAME はリポジトリの名前に置き換えます。

    : fine-grained personal access token を使用している場合は、REPO-OWNERREPO-NAME を、自分が所有している、または自分がメンバーである organization によって所有されているリポジトリに置き換える必要があります。 お使いのトークンは、リポジトリにアクセスできる必要があり、リポジトリの issue に対する読み取りと書き込みのアクセス許可が必要です。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。

    JavaScript
    await octokit.request("POST /repos/{owner}/{repo}/issues", {
      owner: "REPO-OWNER",
      repo: "REPO-NAME",
      title: "Created with the REST API",
      body: "This is a test issue created by the REST API",
    });
    

    request メソッドでは Accept: application/vnd.github+json ヘッダーが自動的に渡されます。 追加のヘッダーまたは別の Accept ヘッダーを渡すには、2 番目の引数として渡されるオブジェクトに headers プロパティを追加します。 headers プロパティの値は、キーがヘッダー名で値がヘッダー値のオブジェクトです。

    たとえば、次のコードは、text/plain の値を持つ content-type ヘッダーと、2022-11-28 の値を持つ X-GitHub-Api-Version ヘッダーを送信します。

    JavaScript
    await octokit.request("GET /octocat", {
      headers: {
        "content-type": "text/plain",
        "X-GitHub-Api-Version": "2022-11-28",
      },
    });
    

応答の使用

要求を行うと、API では、応答状態コードと応答ヘッダー、また場合によっては応答本文が返されます。

応答コードとヘッダーについて

すべての要求で、応答の成功を示す HTTP 状態コードが返されます。 応答コードについて詳しくは、MDN HTTP 応答状態コードに関するドキュメントを参照してください。

さらに、応答には、応答の詳細を示すヘッダーが含まれます。 X- または x- で始まるものは、GitHub のカスタム ヘッダーです。 たとえば、x-ratelimit-remainingx-ratelimit-reset ヘッダーは、一定期間に行うことができる要求の数を示します。

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

たとえば、この要求は、指定したリポジトリの issue の一覧を取得します。

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

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

Octokit.js で要求を行うと、request メソッドでは promise が返されます。 要求が成功した場合、promise は、応答のHTTP 状態コード (status) と応答ヘッダー (headers) を含むオブジェクトに解決されます。 エラーが発生した場合、promise は、応答のHTTP 状態コード (status) と応答ヘッダー (response.headers) を含むオブジェクトに解決されます。

try/catch ブロックを使用して、エラーが発生した場合にそれをキャッチできます。 たとえば、次のスクリプトの要求が成功した場合、そのスクリプトでは状態コードと x-ratelimit-remaining ヘッダーの値がログに記録されます。 要求が成功しなかった場合、スクリプトでは状態コード、x-ratelimit-remaining ヘッダーの値、およびエラー メッセージがログに記録されます。

次の例では、REPO-OWNER をリポジトリを所有するアカウントの名前に置き換え、REPO-NAME をリポジトリの名前に置き換えます。

JavaScript
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}`)
}

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

たとえば、この要求は、指定したリポジトリの issue の一覧を取得します。

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

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

応答本文について

多くのエンドポイントで応答本文が返されます。 特に指定しない限り、応答本文は JSON 形式となります。 空白のフィールドは、省略されずに null として含まれます。 すべてのタイムスタンプは、 ISO 8601フォーマット: YYYY-MM-DDTHH:MM:SSZ の UTC 時間で返されます。

必要な情報を指定する GraphQL API とは異なり、REST API では通常、必要以上の情報が返されます。 必要に応じて、応答を解析して特定の情報を引き出すことができます。

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

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

その後、jq を使用して、各 issue のタイトルと作成者 ID を取得できます。

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

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

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

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

たとえば、各 issue のタイトルと作成者 ID を取得できます。 次の例では、REPO-OWNER をリポジトリを所有するアカウントの名前に置き換え、REPO-NAME をリポジトリの名前に置き換えます。

JavaScript
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}`)
}

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

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

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

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

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

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

詳細表現と概要表現

応答には、個々のリソースまたはリソースの一覧のどちらをフェッチするかに応じて、リソースのすべての属性または属性のサブセットのみを含めることができます。

  • 特定のリポジトリなどの_個々のリソース_をフェッチすると、通常、応答にはそのリソースのすべての属性が含まれます。 これは、リソースの「詳細」表現です。
  • 複数のリポジトリの一覧など、_リソースの一覧_をフェッチすると、応答には各リソースの属性のサブセットのみが含まれます。 これは、リソースの「要約」表現です。

承認によって、表現に含まれる詳細の内容に影響する場合があることにご注意ください。

その理由は、一部の属性は API が提供する計算コストが高いため、GitHub がそれらの属性を概要表現から除外するからです。 これらの属性を取得するには、詳細な表現をフェッチします。

ドキュメントには、各 API メソッドのレスポンス例が記載されています。 レスポンス例は、そのメソッドによって返されるすべての属性を示しています。

ハイパーメディア

すべてのリソースには、他のリソースにリンクしている 1 つ以上の *_url プロパティがある場合があります。 これらは、適切な API クライアントが自身で URL を構築する必要がないように、明示的な URL を提供することを目的としています。 API クライアントでは、これらを使用することを強くお勧めしています。 そうすることで、開発者が将来の API のアップグレードを容易に行うことができます。 すべての URL は、適切な RFC 6570 URI テンプレートであることが想定されています。

その後、uri_template gem などを使用して、これらのテンプレートを展開できます。

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

次のステップ

この記事では、リポジトリの issue を一覧表示して作成する方法について説明しました。 さらに練習する場合は、issue にコメントを付けたり、issue のタイトルを編集したり、issue を閉じてみたりしてください。 詳細については、「issue コメントの作成」「issue の更新」エンドポイントを参照してください。

使用できるエンドポイントについて詳しくは、REST リファレンス ドキュメントを参照してください。