REST API のリソース

スキーマ

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

$ curl -I http(s)://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: 3.3.0
> 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 Enterprise Server REST API を使用して認証する方法は 2 つあります。 認証を必要とするリクエストは、� �所によって 403 Forbidden ではなく 404 Not Found を返します。 これは、許可されていないユーザにプライベートリポジトリが誤って漏洩するのを防ぐためです。

[基本認証]

$ curl -u "username" http(s)://HOSTNAME/api/v3

OAuth2 トークン（ヘッダに送信）

$ curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3

OAuth2 の詳細を確認します。 OAuth2 トークンは、実稼働アプリケーションの Web アプリケーション フローを使用して取得できます。

OAuth2 キー/シークレット

curl -u my_client_id:my_client_secret 'http(s)://HOSTNAME/api/v3/user/repos'

client_id と client_secret を使用しても、ユーザーとして認証されることは ありません。OAuth アプリを識別してレート制限を引き上げる� けです。 アクセス許可はユーザにのみ付与され、アプリケーションには付与されません。また、認証されていないユーザに表示されるデータのみが返されます。 このため、サーバー間のシナリオでのみ OAuth2 キー/シークレットを使用する必要があります。 OAuth アプリケーションのクライアントシークレットをユーザーに漏らさないようにしてく� さい。

プライベート モードでは、OAuth2 キーとシークレットを使用して認証することはできません。認証しようとすると 401 Unauthorized が返されます。 詳細については、「プライベート モードの有効化」を参照してく� さい。

ログイン失敗の制限

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

$ curl -I http(s)://HOSTNAME/api/v3 -u foo:bar
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/enterprise/3.3/rest"
> }

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

$ curl -i http(s)://HOSTNAME/api/v3 -u -u VALID_USERNAME:VALID_PASSWORD 
> HTTP/2 403
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/enterprise/3.3/rest"
> }

パラメーター

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

$ curl -i "http(s)://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 -u username -d '{"scopes":["repo_deployment"]}' http(s)://HOSTNAME/api/v3/authorizations

ルート エンドポイント

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

$ curl -u USERNAME:PASSWORD http(s)://HOSTNAME/api/v3

GraphQL グローバルノード ID

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

クライアントエラー

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

1. 無効な JSON を送信すると、400 Bad Request 応答が返されます。

   HTTP/2 400
   Content-Length: 35
   
   {"message":"Problems parsing JSON"}
   

2. 間違った種類の JSON 値を送信すると、400 Bad Request 応答が発生します。

    HTTP/2 400
    Content-Length: 40
   
    {"message":"Body should be a JSON object"}
   

3. 無効なフィールドを送信すると、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 Enterprise Server REST API では、必要に応じて HTTP リダイレクトが使用されます。 クライアントは、要求がリダイレクトされる可能性があることを想定する必要があります。 HTTP リダイレクトの受信はエラーでは なく、クライアントはそのリダイレクトに従う必要があります。 リダイレクトのレスポンスには、クライアントが要求を繰り返す必要があるリソースの URI を含む Location ヘッダー フィールドがあります。

状態コード	説明
301	Permanent redirection（恒久的なリダイレクト）。 要求に使用した URI は、Location ヘッダー フィールドで指定されたものに置き換えられています。 このリソースに対する今後のすべてのリクエストは、新しい URI に送信する必要があります。
302, 307	Temporary redirection（一時的なリダイレクト）。 要求は、Location ヘッダー フィールドで指定された URI に逐語的に繰り返される必要がありますが、クライアントは今後の要求で元の URI を引き続き使用する必要があります。

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

HTTP 動詞

GitHub Enterprise Server 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 Enterprise Server は、API の速度と信� �性を保護するためにタイ� アウト ウィンドウを変更する権利を留保します。

レート制限

your GitHub Enterprise Server instance へのさまざまな種類の API 要求は、異なるレート制限に従います。

� えて、Search APIには専用の制限があります。 詳細については、REST API のドキュメントの「検索」を参照してく� さい。

個人アカウントからの要求

personal access tokenで認証するダイレクト API 要求は、ユーザーからサーバーへの要求です。 OAuth AppあるいはGitHub Appは、ユーザが認可した後、user-to-serverリクエストをユーザの代わりに発行することもできます。 詳しい情� �については、「personal access tokenの作成」、「OAuth App の承認」、「GitHub App の承認」を参照してく� さい。

GitHub Enterprise Serverは、すべてのuser-to-serverリクエストを認証されたユーザと関連づけます。 OAuth App及びGitHubについては、これはアプリケーションを認可したユーザです。 すべてのuser-to-serverリクエストは、認証されたユーザのレート制限に対してカウントされます。

既定では、"user-to-server" 要求は、認証したユーザーあたり 5,000 件/時に制限されています。 ユーザーによって、またはユーザーが所有している個人用アクセス トークンによって認可されている OAuth アプリケーションからのすべての要求と、ユーザーの認証資� �情� �のいずれかで認証された要求は、そのユーザーについて 5,000 件/時という同じクォータを共有します。

GitHub Appからのリクエスト

GitHub Appからのリクエストは、user-to-serverあるいはserver-to-serverリクエストのいずれかになります。 GitHub アプリのレート制限の詳細については、「GitHub アプリのレート制限」を参照してく� さい。

GitHub Actionsからのリクエスト

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

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

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

レート制限APIとレスポンスのHTTPヘッダは、任意の時点におけるユーザまたはユーザのアプリケーションが利用できるAPIコール数の信� �できるソースです。

レート制限API

レート制限APIを使って、現在の制限に達することなくレート制限のステータスをチェックできます。 詳細については、「レート制限」を参照してく� さい。

レート制限HTTPヘッダ

API リクエストの返された HTTP ヘッダは、現在のレート制限ステータスを示しています。

$ curl -I http(s)://HOSTNAME/api/v3/users/octocat
> HTTP/2 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> 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 エポック秒単位でリセットされる時刻。

時刻に別の形式を使用する必要がある� �合は、最新のプログラミング言語で作業を完了できます。 たとえば、Web ブラウザでコンソールを開くと、リセット時刻を JavaScript の Date オブジェクトとして簡単に取得できます。

new Date(1372700873 * 1000)
// => Mon Jul 01 2013 13:47:53 GMT-0400 (EDT)

レート制限を超えると、次のようなエラーレスポンスが返されます。

> 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/enterprise/3.3/rest/overview/resources-in-the-rest-api#rate-limiting"
> }

OAuth Appの認証されていないレート制限の増� 

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

$ curl -u my_client_id:my_client_secret -I http(s)://HOSTNAME/api/v3/user/repos
> 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 応答をキャッシュし、条件付き要求を使用することで問題を解決できる可能性があります。

セカンダリレート制限

GitHub Enterprise Server で高品質のサービスを提供するにあたって、API を使用するときに、いくつかのアクションに追� のレート制限が適用される� �合があります。 たとえば、API を使用してコンテンツを急速に作成する、webhook を使用する代わりに積極的にポーリングする、複数の同時リクエストを行う、計算コストが高いデータを繰り返しリクエストするなどの行為によって、セカンダリレート制限が適用される� �合があります。

セカンダリレート制限は、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/enterprise/3.3/rest/overview/resources-in-the-rest-api#secondary-rate-limits"
> }

条件付きリクエスト

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

$ curl -I http(s)://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 http(s)://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 http(s)://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 http(s)://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 http(s)://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 Enterprise Server のコンテンツを Web ページに埋め込む� �合に使用されます。 応答には、通常の API と同じデータ出力と、関連する HTTP ヘッダー情� �が含まれます。

$ curl http(s)://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
>       ["http(s)://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 = 'http(s)://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 呼び出しの� �合、その正確なタイ� スタンプを使用します。 その例として、Commits API があります。

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

Time-Zone ヘッダーの使用

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

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

つまり、このヘッダが定義するタイ� ゾーンで API 呼び出しが行われた時のタイ� スタンプが生成されます。 たとえば、Contents API は追� または変更ごとに git コミットを生成し、タイ� スタンプとして現在の時刻を使用します。 このヘッダは、現在のタイ� スタンプの生成に使用されたタイ� ゾーンを決定します。

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

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

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

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