REST API のリソース

スキーマ

API は https://HOSTNAME/api/v3 からアクセスされます。すべてのデータは JSON として送受信されます。

$ curl -I https://HOSTNAME/api/v3/users/octocat/orgs

> HTTP/2 200
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> ETag: "a00049ba79152d03380c34652f2cb612"
> X-GitHub-Media-Type: github.v3
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4987
> x-ratelimit-reset: 1350085394
> X-GitHub-Enterprise-Version: GitHub AE
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff

空白のフィールドは、省略されるのではなく null として含まれます。

すべてのタイムスタンプは、 ISO 8601フォーマットのUTC時間で返されます。

YYYY-MM-DDTHH:MM:SSZ

タイムスタンプのタイムゾーンの詳細については、このセクションを参照してください。

要約表現

リソースのリストをフェッチすると、レスポンスにはそのリソースの属性のサブセットが含まれます。これは、リソースの「要約」表現です。（一部の属性では、API が提供する計算コストが高くなります。パフォーマンス上の理由から、要約表現はそれらの属性を除外します。これらの属性を取得するには、「詳細な」表現をフェッチします。）

例: リポジトリのリストを取得すると、各リポジトリの要約表現が表示されます。ここで、octokit 組織が所有するリポジトリの一覧を取得します。

GET /orgs/octokit/repos

詳細な表現

個々のリソースをフェッチすると、通常、レスポンスにはそのリソースのすべての属性が含まれます。これは、リソースの「詳細」表現です。 (承認によって、表現に含まれる詳細の内容に影響する場合があることにご注意ください。)

例: 個別のリポジトリを取得すると、リポジトリの詳細表現が表示されます。ここで、octokit/octokit.rb リポジトリを取得します。

GET /repos/octokit/octokit.rb

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

認証

GitHub からは、REST API に認証するためのトークンを作成することが推奨されます。作成するトークンの種類について詳しくは、「REST API に対する認証」をご覧ください。

要求の Authorization ヘッダーでトークンを送信することで要求を認証できます。

curl --request GET \
--url "https://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

注: ほとんどの場合は、Authorization: Bearer または Authorization: token を使用してトークンを渡すことができます。ただし、JSON Web トークン (JWT) を渡す場合は、Authorization: Bearer を使用する必要があります。

トークンなしで、またはアクセス許可が不十分なトークンで REST API エンドポイントを使用しようとすると、404 Not Found または 403 Forbidden 応答を受け取ります。

無効な資格情報で認証すると、401 Unauthorized が返されます。

$ curl -I https://HOSTNAME/api/v3 --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/github-ae@latest/rest"
> }

無効な認証情報を含むリクエストを短期間に複数回検出すると、API は、403 Forbidden で、そのユーザに対するすべての認証試行 (有効な認証情報による試行を含む) を一時的に拒否します。

> HTTP/2 403
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/github-ae@latest/rest"
> }

パラメーター

多くの API メソッドはオプションのパラメータを選択しています。 GET リクエストでは、パスのセグメントとして指定されていないパラメーターは、HTTP クエリ文字列型パラメータとして渡すことができます。

$ curl -i "https://HOSTNAME/api/v3/repos/vmg/redcarpet/issues?state=closed"

この例では、'vmg' の値と 'redcarpet' の値がパスの :owner パラメーターと :repo パラメーターに指定されているいっぽうで、:state はクエリ文字列で渡されています。

POST、PATCH、PUT、DELETE の要求については、URL に含まれていないパラメーターは Content-Type が 'application/json' の JSON としてエンコードする必要があります。

$ curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' https://HOSTNAME/api/v3/authorizations

ルートエンドポイント

ルートエンドポイントに GET 要求を発行して、REST API がサポートするすべてのエンドポイントカテゴリを取得できます。

$ curl 
-u USERNAME:TOKEN https://HOSTNAME/api/v3

GraphQL グローバルノード ID

REST API を使用して node_id を検索し、GraphQL 演算で使用する方法の詳細については、「グローバルノードIDの利用」に関するガイドを参照してください。

クライアントエラー

要求の本文を受信する API 呼び出しのクライアントエラーには、次の 3 つの種類があります。

無効な JSON を送信すると、400 Bad Request 応答が返されます。
```
HTTP/2 400
Content-Length: 35

{"message":"Problems parsing JSON"}
```
間違った種類の JSON 値を送信すると、400 Bad Request 応答が発生します。
```
 HTTP/2 400
 Content-Length: 40

 {"message":"Body should be a JSON object"}
```

無効なフィールドを送信すると、422 Unprocessable Entity 応答が発生します。

HTTP/2 422
Content-Length: 149

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "Issue",
      "field": "title",
      "code": "missing_field"
    }
  ]
}

すべてのエラーオブジェクトにはリソースとフィールドのプロパティがあるため、クライアントは何が問題かを認識することができます。また、フィールドの問題点を知らせるエラーコードもあります。

エラーコード	説明
`missing`	リソースが存在しません。
`missing_field`	リソースの必須フィールドが設定されていません。
`invalid`	フィールドのフォーマットが無効です。詳細については、ドキュメントを参照してください。
`already_exists`	別のリソースに、このフィールドと同じ値があります。これは、一意のキー（ラベル名など）が必要なリソースで発生する可能性があります。
`unprocessable`	入力が無効です。

リソースは、カスタム検証エラー (ここでcode は custom) を送信する場合もあります。カスタムエラーには常にエラーを説明する message フィールドがあり、ほとんどのエラーには、エラーの解決に役立つ可能性があるコンテンツを指す documentation_url フィールドも含まれます。

HTTP リダイレクト

GitHub AE REST API では、必要に応じて HTTP リダイレクトが使用されます。クライアントは、要求がリダイレクトされる可能性があることを想定する必要があります。 HTTP リダイレクトの受信はエラーではなく、クライアントはそのリダイレクトに従う必要があります。リダイレクトのレスポンスには、クライアントが要求を繰り返す必要があるリソースの URI を含む Location ヘッダーフィールドがあります。

301 状態コードは、永続的なリダイレクトを示しています。要求に使用した URI は、Location ヘッダーフィールドで指定されたものに置き換えられています。このリソースに対する今後のすべてのリクエストは、新しい URI に送信する必要があります。

302 または 307 状態コードは、一時的なリダイレクトを示しています。要求は、Location ヘッダーフィールドで指定された URI に逐語的に繰り返される必要がありますが、クライアントは今後の要求で元の URI を引き続き使用する必要があります。

その他のリダイレクトステータスコードは、HTTP 1.1 仕様に従って使用できます。

HTTP 動詞

GitHub AE REST API では、可能な限り、各アクションに適した HTTP 動詞を使用しようとします。 HTTP 動詞では大文字と小文字が区別されることにご注意ください。

動詞	説明
`HEAD`	HTTP ヘッダ情報のみを取得するために、任意のリソースに対して発行できます。
`GET`	リソースを取得するために使用します。
`POST`	リソースを作成するために使用します。
`PATCH`	部分的な JSON データでリソースを更新するために使用します。たとえば、Issue リソースには `title` 属性と `body` 属性があります。 `PATCH` 要求は、リソースを更新するために 1 つ以上の属性を受け入れることができます。
`PUT`	リソースまたはコレクションを置き換えるために使用します。 `body` 属性のない `PUT` 要求の場合は、必ず `Content-Length` ヘッダーを 0 に設定してください。
`DELETE`	リソースを削除するために使用します。

ハイパーメディア

すべてのリソースには、他のリソースにリンクしている 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"

改ページ位置の自動修正

REST API からの応答にたくさんの結果が含まれるとき、GitHub ではページが分割され、結果のサブセットが返されます。応答のリンクヘッダーを利用し、データの追加ページを要求できます。 per_page クエリパラメーターがエンドポイントでサポートされる場合、1 ページで返される結果の数を制御できます。改ページ位置の自動修正の詳細については、「REST API 内での改ページ位置の自動修正の使用」を参照してください。

Timeouts

GitHub が API を処理するのに 10 秒以上かかると、次に示すように、GitHub はリクエストを終了させ、タイムアウトの応答が返されます。

{
    "message": "Server Error"
}

GitHub AE は、API の速度と信頼性を保護するためにタイムアウトウィンドウを変更する権利を留保します。

レート制限

GitHub AE REST API では、レート制限を使用して API トラフィックを制御します。 API 要求の種類が異なれば、レート制限も異なります。応答ヘッダーは、現在のレート制限の状態を示しています。

転送率の制限

ご自分のエンタープライズへのさまざまな種類の API 要求は、異なるレート制限に従います。さらに、検索エンドポイントには専用の制限があります。詳しくは、REST API ドキュメントの「検索」をご覧ください。

個人アカウントからの要求のレート制限

personal access token で認証するという直接の API 要求を行うことができます。 OAuth App または GitHub App でも、アプリの認証後に、ユーザーに代わって要求を行うことができます。詳しくは、「Managing your personal access tokens」、「OAuth アプリの承認」、「GitHub App の承認」をご覧ください。

GitHub AE によってこれらの要求がすべて、認証されたユーザーに関連付けられます。 OAuth Apps と GitHub Apps については、これがアプリを認証したユーザーです。これらの要求はすべて、ユーザーのレート制限まで数えられます。

ユーザーアクセストークンの要求は、認証したユーザーあたり 15,000 件/時に制限されています。ユーザーによって、またはユーザーが所有している personal access token によって認可されている OAuth アプリケーションからのすべての要求と、ユーザーの認証資格情報のいずれかで認証された要求は、そのユーザーについて 1 時間あたり 15,000 件の同じクォータを共有します。

GitHub Apps からの要求のレート制限

GitHub App からの要求では、ユーザーアクセストークンかインストールアクセストークンが使用されます。 GitHub Apps のレート制限について詳しくは、「Rate limits for GitHub Apps (GitHub アプリのレート制限)」をご覧ください。

GitHub Actions からの要求のレート制限

GitHub Actions ワークフロー内の要求の認証には、組み込みの GITHUB_TOKEN を使用できます。詳しくは、「自動トークン認証」を参照してください。

GITHUB_TOKEN を使用する場合、レート制限は、リポジトリごとに 1 時間あたり 1,000 要求です。

レート制限のステータスのチェック

応答ヘッダーは、現在のレート制限の状態を示しています。 REST API を使用して、任意の時点で自分または自分のアプリで使用できる API 呼び出しの現在の数を見つけることもできます。

レート制限ヘッダー

x-ratelimit 応答ヘッダーでは、各要求の後に現在のレート制限の状態を示しています。

$ curl -i https://HOSTNAME/api/v3/users/octocat
> HTTP/2 200
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 56
> x-ratelimit-used: 4
> x-ratelimit-reset: 1372700873

ヘッダー名	説明
`x-ratelimit-limit`	1 時間あたりのリクエスト数の上限。
`x-ratelimit-remaining`	現在のレート制限ウィンドウに残っているリクエストの数。
`x-ratelimit-used`	現在のレート制限ウィンドウに残っているリクエストの数。
`x-ratelimit-reset`	現在のレート制限ウィンドウが UTC エポック秒単位でリセットされる時刻。

REST API を使ったレート制限の状態チェック

REST API を使って、現在の制限に達することなくレート制限の状態をチェックできます。詳しくは、「レート制限」を参照してください。可能であれば、GitHub では、代わりに x-ratelimit 応答ヘッダーを使用して API の負荷を軽減することをお勧めします。

レート制限の超過

レート制限を超えると、応答は 403 状態になり、x-ratelimit-remaining ヘッダーは 0 になります。

> HTTP/2 403
> Date: Tue, 20 Aug 2013 14:50:41 GMT
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 0
> x-ratelimit-used: 60
> x-ratelimit-reset: 1377013266

> {
>    "message": "API rate limit exceeded for xxx.xxx.xxx.xxx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
>    "documentation_url": "https://docs.github.com/github-ae@latest/rest/overview/resources-in-the-rest-api#rate-limiting"
> }

レートが制限されている場合は、x-ratelimit-reset 時間で指定された時刻の後まで要求を試行しないでください。

OAuth Apps の未認証レート制限を増やす

OAuth App でパブリックリソースの未認証呼び出しをより高いレート制限で行う必要がある場合は、エンドポイントルートの前にアプリのクライアント ID とシークレットを渡すことができます。

$ curl -u my_client_id:my_client_secret -I https://HOSTNAME/api/v3/meta
> HTTP/2 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4966
> x-ratelimit-used: 34
> x-ratelimit-reset: 1372700873

注: クライアントシークレットを他のユーザーと共有したり、クライアント側のブラウザーコードに含めたりしないでください。

レート制限内に収める

基本認証または OAuth を使用してレート制限を超えた場合は、API 応答をキャッシュし、条件付き要求を使用することで問題を解決できる可能性があります。

セカンダリレート制限

上記のレート制限は REST API 全体に適用され、ユーザーごとまたはアプリごとです。 GitHub AE で高品質のサービスを提供するにあたって、API を使用するときに、いくつかのアクションに追加のレート制限が適用される場合があります。たとえば、コンテンツを迅速に作成する、webhook を使用するのではなく積極的にポーリングする、複数の同時要求を行う、計算コストが高いデータを繰り返し要求するために API を使用すると、追加のレート制限が適用される場合があります。

これらの追加のレート制限は、API の正当な使用を妨げることを意図したものではありません。通常のレート制限が、ユーザにとって唯一の制限であるべきです。優良な API ユーザーにふさわしい振る舞いをしているかどうかを確認するには、「ベストプラクティスのガイドライン」を参照してください。

アプリケーションによって追加のレート制限がトリガーされると、次のような有益な応答を受け取ります。

> HTTP/2 403
> Content-Type: application/json; charset=utf-8
> Connection: close

> {
>   "message": "You have exceeded a secondary rate limit and have been temporarily blocked from content creation. Please retry your request again later.",
>   "documentation_url": "https://docs.github.com/github-ae@latest/rest/overview/resources-in-the-rest-api#secondary-rate-limits"
> }

待ってから、後で要求を試す必要があります。 retry-after 応答ヘッダーが存在する場合は、その秒数が経過するまで要求を再試行しないでください。 x-ratelimit-remaining ヘッダーが 0 の場合、x-ratelimit-reset ヘッダーで指定された時刻 (UTC エポック秒数) まで要求を再試行しないでください。それ以外の場合は、再試行の間の時間が指数関数的に増えるのを待機し、特定の回数の再試行の後にエラーをスローします。

条件付きリクエスト

ほとんどの応答では ETag ヘッダーが返されます。多くの応答では Last-Modified ヘッダーも返されます。これらのヘッダーの値を使用して、それぞれ If-None-Match のヘッダーと If-Modified-Since のヘッダーを使用してそれらのリソースに対する後続の要求を行うことができます。リソースが変更されていない場合、サーバーは 304 Not Modified を返します。

$ curl -I https://HOSTNAME/api/v3/user
> HTTP/2 200
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

$ curl -I https://HOSTNAME/api/v3/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
> HTTP/2 304
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

$ curl -I https://HOSTNAME/api/v3/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
> HTTP/2 304
> Cache-Control: private, max-age=60
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

API では、任意のオリジンからの AJAX 要求に対して、オリジン間リソース共有 (CORS) がサポートされています。「CORS W3C の推奨事項」、または HTML 5 セキュリティガイドの「この概要」をお読みください。

http://example.com をヒットするブラウザーから送信されたサンプル要求を次に示します。

$ curl -I https://HOSTNAME/api/v3 -H "Origin: http://example.com"
HTTP/2 302
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval

CORS プリフライトリクエストは次のようになります。

$ curl -I https://HOSTNAME/api/v3 -H "Origin: http://example.com" -X OPTIONS
HTTP/2 204
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400

JSON-P コールバック

?callback パラメーターを任意の GET 呼び出しに送信して、結果を JSON 関数でラップできます。これは通常、クロスドメインの問題を回避することにより、ブラウザーが GitHub AE のコンテンツを Web ページに埋め込む場合に使用されます。応答には、通常の API と同じデータ出力と、関連する HTTP ヘッダー情報が含まれます。

$ curl https://HOSTNAME/api/v3?callback=foo

> /**/foo({
>   "meta": {
>     "status": 200,
>     "x-ratelimit-limit": "5000",
>     "x-ratelimit-remaining": "4966",
>     "x-ratelimit-reset": "1372700873",
>     "Link": [ // pagination headers and other links
>       ["https://HOSTNAME/api/v3?page=2", {"rel": "next"}]
>     ]
>   },
>   "data": {
>     // the data
>   }
> })

JavaScript ハンドラを記述して、コールバックを処理できます。以下は、試すことができる最も簡易な例です。

<html>
<head>
<script type="text/javascript">
function foo(response) {
  var meta = response.meta;
  var data = response.data;
  console.log(meta);
  console.log(data);
}

var script = document.createElement('script');
script.src = 'https://HOSTNAME/api/v3?callback=foo';

document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>

<body>
  <p>Open up your browser's console.</p>
</body>
</html>

すべてのヘッダーは HTTP ヘッダーと同じ文字列型の値ですが、例外の 1 つとして "Link" があります。 Link ヘッダーは事前に解析され、[url, options] タプルの配列として渡されます。

リンクは次のようになります。

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

... コールバック出力では次のようになります。

{
  "Link": [
    [
      "url1",
      {
        "rel": "next"
      }
    ],
    [
      "url2",
      {
        "rel": "foo",
        "bar": "baz"
      }
    ]
  ]
}

タイムゾーン

新しいコミットの作成など、新しいデータを作成する一部のリクエストでは、タイムスタンプを指定または生成するときにタイムゾーン情報を提供できます。そういったAPI 呼び出しのタイムゾーン情報を決定する際に、優先順位に従って次のルールを適用します。

ISO 8601 タイムスタンプにタイムゾーン情報を明示的に提供する
Time-Zone ヘッダーの使用
ユーザーが最後に認識されたタイムゾーンを使用する
他のタイムゾーン情報を含まない UTC を既定値に設定する

これらのルールは、APIに渡されたデータに対してのみ適用され、APIが返す日付には適用されないことに注意してください。 "スキーマ" にあるように、API が返すタイムスタンプは UTC 時間であり、ISO 8601 形式です。

ISO 8601 タイムスタンプにタイムゾーン情報を明示的に提供する

タイムスタンプを指定できる API 呼び出しの場合、その正確なタイムスタンプを使用します。この例として、コミットを管理する API があります。詳しくは、「Git データベース」を参照してください。

これらのタイムスタンプは 2014-02-27T15:05:06+01:00 のようになります。これらのタイムスタンプを指定する方法については、この例も参照してください。

`Time-Zone` ヘッダーの使用

Olson データベースの名前の一覧に従ってタイムゾーンを定義する Time-Zone ヘッダーを指定できます。

$ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://HOSTNAME/api/v3/repos/github-linguist/linguist/contents/new_file.md

つまり、このヘッダが定義するタイムゾーンで API 呼び出しが行われた時のタイムスタンプが生成されます。たとえば、コンテンツを管理するための API によって、追加または変更するごとに git コミットが生成され、タイムスタンプとして現在の時刻が使用されます。詳しくは、「リポジトリ」を参照してください。このヘッダは、現在のタイムスタンプの生成に使用されたタイムゾーンを決定します。

ユーザが最後に認識されたタイムゾーンを使用する

Time-Zone ヘッダーが指定されておらず、API への認証された呼び出しを行う場合、認証されたユーザーが最後に認識されたタイムゾーンが使用されます。最後に認識されたタイムゾーンは、GitHub AE Web サイトを閲覧するたびに更新されます。

他のタイムゾーン情報を含まない UTC をデフォルトにする

上記の手順で情報が得られない場合は、UTC をタイムゾーンとして使用して git コミットを作成します。

REST API のリソース

この記事の内容