はじめに
この記事では、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 から連絡できます。
次の例は、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 時間あたりの要求を増やすことができます。
一部の REST API エンドポイントには認証なしでアクセスできますが、GitHub CLI では、api
サブコマンドを使用して API 要求を行う前に認証する必要があります。 auth login
サブコマンドを使用して、 に対する認証を行います。 詳細については、「要求の作成」を参照してください。
パラメーター
多くの API メソッドでは、要求のパラメーターに追加情報を送信する必要があります。 パラメーターには、パス パラメーター、本文パラメーター、クエリ パラメーターなど、いくつかの種類があります。
パス パラメーター
パス パラメーターではエンドポイントパスを変更します。 これらは要求に必須です。 詳細については、「Path」をご覧ください。
本文パラメータ
本文パラメーターを使用すると、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
が使用されます。 -
必要なパス パラメーターを特定します。 必要なパス パラメーターは、エンドポイントのパスの中かっこ
{}
で囲まれています。 各パラメーターのプレースホルダーを目的の値に置き換えます。 詳細については、「Path」をご覧ください。たとえば、"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' \
応答の使用
要求を行うと、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
で、要求が成功したことを示します。
応答本文について
多くのエンドポイントで応答本文が返されます。 特に指定しない限り、応答本文は 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 のドキュメントをご覧ください。
詳細表現と概要表現
応答には、個々のリソースまたはリソースの一覧のどちらをフェッチするかに応じて、リソースのすべての属性または属性のサブセットのみを含めることができます。
- 特定のリポジトリなどの_個々のリソース_をフェッチすると、通常、応答にはそのリソースのすべての属性が含まれます。 これは、リソースの「詳細」表現です。
- 複数のリポジトリの一覧など、_リソースの一覧_をフェッチすると、応答には各リソースの属性のサブセットのみが含まれます。 これは、リソースの「要約」表現です。
承認によって、表現に含まれる詳細の内容に影響する場合があることにご注意ください。
その理由は、一部の属性は 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 リファレンス ドキュメントを参照してください。