はじめに
この記事では、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 メソッドには GET
、POST
、DELETE
、PATCH
があります。 REST API リファレンス ドキュメントには、すべてのエンドポイントの HTTP メソッドが記載されています。
たとえば、「リポジトリの issue の一覧表示」エンドポイントの HTTP メソッドは GET
です。
GitHub 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 のバージョン」を参照してください。
User-Agent
すべての API 要求に有効な User-Agent
ヘッダーを含める必要があります。 User-Agent
ヘッダーは、要求を行っているユーザーまたはアプリケーションを識別します。
既定では、GitHub CLI は有効な User-Agent
ヘッダーを送信します。 ただし、GitHub では、User-Agent
ヘッダー値に GitHub ユーザー名またはアプリケーションの名前を使用することをおすすめします。 これにより、問題が発生した場合に GitHub から連絡できます。
既定で、curl
は有効な User-Agent
ヘッダーを送信します。 ただし、GitHub では、User-Agent
ヘッダー値に GitHub ユーザー名またはアプリケーションの名前を使用することをおすすめします。 これにより、問題が発生した場合に GitHub から連絡できます。
Octokit.js SDK を使用すると、SDK から有効な User-Agent
ヘッダーが送信されます。 ただし、GitHub では、User-Agent
ヘッダー値に GitHub ユーザー名またはアプリケーションの名前を使用することをおすすめします。 これにより、問題が発生した場合に GitHub から連絡できます。
次の例は、Awesome-Octocat-App
という名前のアプリの例 User-Agent
です。
User-Agent: Awesome-Octocat-App
User-Agent
ヘッダーのない要求は拒否されます。 無効な User-Agent
ヘッダーを指定すると、403 Forbidden
応答を受け取ります。
メディアの種類
1 つ以上のメディアの種類を指定するには、それらを要求のAccept
ヘッダーに 追加します。 Accept
ヘッダーの詳細については、「Accept
」を参照してください。
メディアの種類は、API から使用するデータの形式を指定します。 メディアの種類はリソースに固有であるため、個別に変更したり、他のリソースではサポートされていない形式をサポートしたりできます。 各 GitHub REST API エンドポイントのドキュメントでは、サポートされているメディアの種類について説明します。 詳しくは、「GitHub REST API に関するドキュメント」をご覧ください。
GitHub REST API でサポートされる最も一般的なメディアの種類は application/vnd.github+json
と application/json
です。
一部のエンドポイントで使用できるカスタム メディアの種類があります。 たとえば、コミットと pull request を管理する REST API では、diff
、patch
、sha
というメディアの種類がサポートされます。 full
、raw
、text
、html
というメディアの種類は、他のエンドポイントで使用されます。
GitHub のすべてのカスタム メディアの種類は次のようになります。application/vnd.github.PARAM+json
。PARAM
がメディアの種類の名前です。 たとえば、raw
メディアの種類を指定するには、application/vnd.github.raw+json
を使用します。
メディアの種類を使用する要求の例については、「要求の作成」を参照してください。
認証
多くのエンドポイント操作では、認証が必要であるか、認証されている場合は追加情報が返されます。 さらに、認証されている場合は 1 時間あたりの要求を増やすことができます。
要求を認証するには、必要なスコープまたはアクセス許可を持つ認証トークンを提供する必要があります。 トークンを取得するには、いくつかの方法があります。personal access token を作成したり、GitHub App を使ってトークンを生成したり、GitHub Actions ワークフローに組み込まれているGITHUB_TOKEN
を使用したりできます。 詳しくは、「REST API に対する認証」を参照してください。
認証トークンを使用する要求の例については、「要求の作成」を参照してください。
Note
トークンを作成したくない場合は、GitHub CLI を使用できます。 GitHub CLI は認証を処理し、アカウントのセキュリティを維持するのに役立ちます。 詳しくは、このページのGitHub CLI バージョンを参照してください。
Warning
アクセス トークンは、パスワードや他の機密性の高い資格情報を扱うのと同じ方法で扱ってください。 詳しくは、「API 資格情報をセキュリティで保護する」を参照してください。
一部の REST API エンドポイントには認証なしでアクセスできますが、GitHub CLI では、api
サブコマンドを使用して API 要求を行う前に認証する必要があります。 auth login
サブコマンドを使用して、 に対する認証を行います。 詳細については、「要求の作成」を参照してください。
要求を認証するには、必要なスコープまたはアクセス許可を持つ認証トークンを提供する必要があります。 トークンを取得するには、いくつかの方法があります。personal access token を作成したり、GitHub App を使ってトークンを生成したり、GitHub Actions ワークフローに組み込まれているGITHUB_TOKEN
を使用したりできます。 詳しくは、「REST API に対する認証」を参照してください。
認証トークンを使用する要求の例については、「要求の作成」を参照してください。
Warning
アクセス トークンは、パスワードや他の機密性の高い資格情報を扱うのと同じ方法で扱ってください。 詳しくは、「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. 認証
-
GitHub に対して認証を行うには、ターミナルから次のコマンドを実行します。
gh auth login
--scopes
オプションを使用して、必要なスコープを指定できます。 作成したトークンで認証する場合は、--with-token
オプションを使用できます。 詳しくは、GitHub CLIauth login
のドキュメントを参照してください。 -
認証を行う場所を選びます。
- GitHub.com にある GitHub にアクセスする場合は、[GitHub.com] を選びます。
- 別のドメインにある GitHub にアクセスする場合は、[Other] を選んでから、ホスト名を入力します (例:
octocorp.ghe.com
)。
-
画面上の残りのプロンプトに従います。
GitHub CLI は、Git 操作の優先プロトコルとして HTTPS を選択すると自動的に Git 資格情報を格納し、GitHub 資格情報で Git に対して認証するかどうかを尋ねるプロンプトに対して "はい" と答えます。 これは、別の資格情報マネージャーを設定したり、SSH を使用したりすることなく、
git push
やgit pull
などの Git を使用できるので便利です。
3. 要求のエンドポイントの選択
-
要求を行うエンドポイントを選びます。 GitHub の REST API ドキュメント を調べて、GitHub とやりとりするために使用できるエンドポイントを検出できます。
-
エンドポイントの HTTP メソッドとパスを特定します。 これらは要求と共に送信されます。 詳細については、「HTTP メソッド」と「 パス」を参照してください。
たとえば、"issue の作成" エンドポイント では、HTTP メソッド
POST
とパス/repos/{owner}/{repo}/issues
が使用されます。 -
必要なパス パラメーターを特定します。 必要なパス パラメーターは、エンドポイントのパスの中かっこ
{}
で囲まれています。 各パラメーターのプレースホルダーを目的の値に置き換えます。 詳細については、「パス」を参照してください。たとえば、"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 アートとして返します。
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"
クエリ パラメーターを使用した要求の例
"パブリック イベントの一覧表示" エンドポイント では、既定で 30 個の issue が返されます。 次の例では、per_page
クエリ パラメーターを使用して 30 個ではなく 2 個の issue を返し、page
クエリ パラメーターを使用して結果の最初のページのみをフェッチします。
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' \
本文パラメーターを使用した要求の例
次の例では、"issue の作成" エンドポイント を使用して、octocat/Spoon-Knife リポジトリに新しい issue を作成します。応答で issue の html_url
を見つけ、ブラウザーの issue に移動します。
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
を使用して、GitHub REST API に対して認証済み要求を行う方法について説明します。
1. セットアップ
お使いのコンピューター上に curl
がインストールされている必要があります。 curl
が既にインストールされているかどうかを確認するには、コマンド ラインで curl --version
を実行します。
- 出力が
curl
のバージョンに関する情報であれば、curl
がインストールされているということです。 command not found: curl
のようなメッセージが表示された場合は、curl
がインストールされていないことを意味します。curl
をダウンロードしてインストールします。 詳しくは、curl のダウンロードに関するページを参照してください。
2. 要求のエンドポイントの選択
-
要求を行うエンドポイントを選びます。 GitHub の REST API ドキュメント を調べて、GitHub とやりとりするために使用できるエンドポイントを検出できます。
-
エンドポイントの HTTP メソッドとパスを特定します。 これらは要求と共に送信されます。 詳細については、「HTTP メソッド」と「 パス」を参照してください。
たとえば、"issue の作成" エンドポイント では、HTTP メソッド
POST
とパス/repos/{owner}/{repo}/issues
が使用されます。 -
必要なパス パラメーターを特定します。 必要なパス パラメーターは、エンドポイントのパスの中かっこ
{}
で囲まれています。 各パラメーターのプレースホルダーを目的の値に置き換えます。 詳細については、「パス」を参照してください。たとえば、"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.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
を前の手順で作成した認証トークンに置き換えます。
Note
fine-grained personal access token を使っている場合は、octocat/Spoon-Knife
を、自分が所有している、または自分がメンバーである organization によって所有されているリポジトリに置き換える必要があります。 お使いのトークンは、リポジトリにアクセスできる必要があり、リポジトリの issue に対する読み取りと書き込みのアクセス許可が必要です。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。
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"
}'
このセクションでは、JavaScript と Octokit.js を使用して GitHub REST API に要求する方法について説明します。 さらに詳しいガイドについては、「REST API と JavaScript を使用したスクリプト」をご覧ください。
1. セットアップ
次の例に示す Octokit.js ライブラリを使用するには、octokit
をインストールする必要があります。
octokit
をインストールする。 たとえば、「npm install octokit
」のように入力します。octokit
をインストールまたは読み込むための他の方法については、Octokit.js の README を参照してください。
2. 要求のエンドポイントの選択
-
要求を行うエンドポイントを選びます。 GitHub の REST API ドキュメント を調べて、GitHub とやりとりするために使用できるエンドポイントを検出できます。
-
エンドポイントの HTTP メソッドとパスを特定します。 これらは要求と共に送信されます。 詳細については、「HTTP メソッド」と「 パス」を参照してください。
たとえば、"issue の作成" エンドポイント では、HTTP メソッド
POST
とパス/repos/{owner}/{repo}/issues
が使用されます。 -
必要なパス パラメーターを特定します。 必要なパス パラメーターは、エンドポイントのパスの中かっこ
{}
で囲まれています。 各パラメーターのプレースホルダーを目的の値に置き換えます。 詳細については、「パス」を参照してください。たとえば、"issue の作成" エンドポイント ではパス
/repos/{owner}/{repo}/issues
が使用され、パス パラメーターは{owner}
と{repo}
になります。 API 要求でこのパスを使用するには、{repo}
を新しい issue を作成するリポジトリの名前に置き換え、{owner}
をリポジトリを所有するアカウントの名前に置き換えます。
3. アクセス トークンの作成
要求を認証するためのアクセス トークンを作成します。 トークンを保存し、複数の要求に使用できます。 エンドポイントにアクセスするために必要なスコープまたはアクセス許可をトークンに付与します。 このトークンは要求の Authorization
ヘッダーに含めて送信します。 詳細については、認証に関するページをご覧ください。
4. Octokit.js で要求を行う
-
スクリプトで
octokit
をインポートします。 たとえば、「import { Octokit } from "octokit";
」のように入力します。 その他のoctokit
のインポート方法については、Octokit.js の README を参照してください。 -
トークンを使用して
Octokit
のインスタンスを作成します。YOUR-TOKEN
をお使いのトークンに置き換えます。JavaScript const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
-
octokit.request
を使用して、要求を実行します。- HTTP メソッドとパスを
request
メソッドの最初の引数として送信します。 詳細については、「HTTP メソッド」と「 パス」を参照してください。 - オブジェクト内のすべてのパス、クエリ、および本文パラメーターを
request
メソッドの 2 番目の引数として指定します。 詳しくは、「パラメーター」をご覧ください。
次の要求例では、HTTP メソッドは
POST
、パスは/repos/{owner}/{repo}/issues
、パス パラメーターはowner: "octocat"
とrepo: "Spoon-Knife"
、本文パラメーターはtitle: "Created with the REST API"
とbody: "This is a test issue created by the REST API"
です。Note
fine-grained personal access token を使っている場合は、
octocat/Spoon-Knife
を、自分が所有している、または自分がメンバーである organization によって所有されているリポジトリに置き換える必要があります。 お使いのトークンは、リポジトリにアクセスできる必要があり、リポジトリの issue に対する読み取りと書き込みのアクセス許可が必要です。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。JavaScript await octokit.request("POST /repos/{owner}/{repo}/issues", { owner: "octocat", repo: "Spoon-Knife", title: "Created with the REST API", body: "This is a test issue created by the REST API", });
await octokit.request("POST /repos/{owner}/{repo}/issues", { owner: "octocat", repo: "Spoon-Knife", 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", }, });
await octokit.request("GET /octocat", { headers: { "content-type": "text/plain", "X-GitHub-Api-Version": "2022-11-28", }, });
- HTTP メソッドとパスを
応答の使用
要求を行うと、API では、応答状態コードと応答ヘッダー、また場合によっては応答本文が返されます。
応答コードとヘッダーについて
すべての要求で、応答の成功を示す HTTP 状態コードが返されます。 応答コードについて詳しくは、MDN HTTP 応答状態コードに関するドキュメントを参照してください。
さらに、応答には、応答の詳細を示すヘッダーが含まれます。 X-
または x-
で始まるものは、GitHub のカスタム ヘッダーです。 たとえば、x-ratelimit-remaining
と x-ratelimit-reset
ヘッダーは、一定期間に行うことができる要求の数を示します。
状態コードとヘッダーを表示するには、要求を送信するときに --include
または --i
オプションを使用します。
たとえば、この要求は、octocat/Spoon-Knife リポジトリの issue の一覧を取得します。
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
この例では、応答コードは 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
をリポジトリの名前に置き換えます。
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}`)
}
状態コードとヘッダーを表示するには、要求を送信するときに --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
で、要求が成功したことを示します。
応答本文について
多くのエンドポイントで応答本文が返されます。 特に指定しない限り、応答本文は JSON 形式となります。 空白のフィールドは、省略されずに null
として含まれます。 すべてのタイムスタンプは、 ISO 8601フォーマット: YYYY-MM-DDTHH:MM:SSZ
の UTC 時間で返されます。
必要な情報を指定する GraphQL API とは異なり、REST API では通常、必要以上の情報が返されます。 必要に応じて、応答を解析して特定の情報を引き出すことができます。
たとえば、>
を使用して、応答をファイルにリダイレクトできます。 次の例では、REPO-OWNER
をリポジトリを所有するアカウントの名前に置き換え、REPO-NAME
をリポジトリの名前に置き換えます。
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 を使用して、各 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 のドキュメントをご覧ください。
たとえば、各 issue のタイトルと作成者 ID を取得できます。 次の例では、REPO-OWNER
をリポジトリを所有するアカウントの名前に置き換え、REPO-NAME
をリポジトリの名前に置き換えます。
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}`)
}
たとえば、>
を使用して、応答をファイルにリダイレクトできます。 次の例では、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 のドキュメントをご覧ください。
詳細表現と概要表現
応答には、個々のリソースまたはリソースの一覧のどちらをフェッチするかに応じて、リソースのすべての属性または属性のサブセットのみを含めることができます。
- 特定のリポジトリなどの_個々のリソース_をフェッチすると、通常、応答にはそのリソースのすべての属性が含まれます。 これは、リソースの「詳細」表現です。
- 複数のリポジトリの一覧など、_リソースの一覧_をフェッチすると、応答には各リソースの属性のサブセットのみが含まれます。 これは、リソースの「要約」表現です。
承認によって、表現に含まれる詳細の内容に影響する場合があることにご注意ください。
その理由は、一部の属性は 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 リファレンス ドキュメントを参照してください。