REST API のリソース

公式の GitHub Enterprise Server REST API を構成するリソースについて説明しています。 ご不明な点やご要望がございましたら、your site administrator までご連絡ください。

最新バージョン

デフォルトでは、http(s)://[hostname]/api/v3 へのすべてのリクエストが REST API の v3 バージョンを受け取ります。 Accept ヘッダを介してこのバージョンを明示的にリクエストすることをお勧めします。

Accept: application/vnd.github.v3+json

スキーマ

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: 2.22.0
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff

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

すべてのタイムスタンプは ISO 8601 形式で返されます。

YYYY-MM-DDTHH:MM:SSZ

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

要約表現

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

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

GET /orgs/octokit/repos

詳細な表現

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

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

GET /repos/octokit/octokit.rb

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

認証

GitHub Enterprise Server REST API を使用して認証する方法は 2 つあります。 認証を必要とするリクエストは、場所によって 403 Forbidden ではなく 404 Not Found を返します。 これは、許可されていないユーザにプライベートリポジトリが誤って漏洩するのを防ぐためです。

Basic 認証

$ curl -u "username" http(s)://[hostname]/api/v3

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

$ curl -H "Authorization: token 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/2.22/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/2.22/rest"
> }

パラメータ

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

$ curl -i "http(s)://[hostname]/api/v3/repos/vmg/redcarpet/issues?state=closed"

この例では、パスの :owner と :repo パラメータに「vmg」と「redcarpet」の値が指定され、クエリ文字列型で :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 リダイレクト

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

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

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

HTTP メソッド

API v3 は、可能な限り各アクションに適切な HTTPメソッドを使用しようとします。

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

ハイパーメディア

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

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

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

ページネーション

複数のアイテムを返すリクエストは、デフォルトで 30 件ごとにページ分けされます。 page パラメータを使用すると、さらにページを指定できます。 一部のリソースでは、per_page パラメータを使用してカスタムページサイズを最大 100 に設定することもできます。 技術的な理由により、すべてのエンドポイントが per_page パラメータを尊重するわけではないことに注意してください。例については、イベントを参照してください。

$ curl 'http(s)://[hostname]/api/v3/user/repos?page=2&per_page=100'

ページ番号は 1 から始まり、page パラメータを省略すると最初のページが返されることに注意してください。

カーソルベースのページネーションを使用するエンドポイントもあります。 カーソルとは、結果セットで場所を示す文字列です。 カーソルベースのページネーションでは、結果セットで「ページ」という概念がなくなるため、特定のページに移動することはできません。 かわりに、before または after パラメータを使用して結果の中を移動できます。

ページネーションの詳細については、ページネーションでトラバースするのガイドをご覧ください。

リンクヘッダ

The Link header includes pagination information. 例:

Link: <http(s)://[hostname]/api/v3/user/repos?page=3&per_page=100>; rel="next",
  <http(s)://[hostname]/api/v3/user/repos?page=50&per_page=100>; rel="last"

この例は、読みやすいように改行されています。

エンドポイントでカーソルベースのページネーションを使用する場合:

Link: <http(s)://[hostname]/api/v3/orgs/ORG/audit-log?after=MTYwMTkxOTU5NjQxM3xZbGI4VE5EZ1dvZTlla09uWjhoZFpR&before=>; rel="next",

This Link response header contains one or more Hypermedia link relations, some of which may require expansion as URI templates.

使用可能な rel の値は以下のとおりです。

名前	説明
次	結果のすぐ次のページのリンク関係。
last	結果の最後のページのリンク関係。
first	結果の最初のページのリンク関係。
prev	結果の直前のページのリンク関係。

レート制限

Basic 認証または OAuth を使用する API リクエストの場合、1 時間あたり最大 5,000 件のリクエストを作成できます。 認証されたリクエストは、Basic 認証または OAuth トークンのどちらが使用されたかに関係なく、認証されたユーザに関連付けられます。 つまり、ユーザが認証したすべての OAuth アプリケーションは、同じユーザが所有する異なるトークンで認証する場合、1 時間あたり 5,000 リクエストという同じ割り当てを共有します。

ビルトインのGITHUB_TOKENをGitHub Actionsで使う場合、レート制限はリポジトリごとに1時間あたり1,000リクエストです。 GitHub Enterprise Cloudアカウントに属するOrganizationでは、この制限はリポジトリごとに1時間あたり15,000リクエストです。

認証されていないリクエストでは、レート制限により 1 時間あたり最大 60 リクエストまで可能です。 認証されていないリクエストは、リクエストを行っているユーザではなく、発信元の IP アドレスに関連付けられます。

上記の制限は GitHub Enterprise Serverのデフォルトのレート制限であることに注意してください。 レート制限が有効化されており、どのように設定されているかを確認するにはサイト管理者に連絡してください。

Search API にはカスタムのレート制限ルールがあることに注意してください。

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-Reset: 1372700873

ヘッダ名	説明
X-RateLimit-Limit	1 時間あたりのリクエスト数の上限。
X-RateLimit-Remaining	現在のレート制限ウィンドウに残っているリクエストの数。
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-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/2.22/rest/overview/resources-in-the-rest-api#rate-limiting"
> }

API ヒットを発生させることなく、レート制限ステータスを確認できます。

OAuth アプリケーションの認証されていないレート制限を増やす

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

$ curl -u my_client_id:my_client_secret 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-Reset: 1372700873

レート制限内に収める

Basic 認証または OAuth を使用してレート制限を超えた場合、API レスポンスをキャッシュし、条件付きリクエストを使用することで問題を解決できます。

Secondary rate limits

GitHub Enterprise Server で高品質のサービスを提供するにあたって、API を使用するときに、いくつかのアクションに追加のレート制限が適用される場合があります。 For example, using the API to rapidly create content, poll aggressively instead of using webhooks, make multiple concurrent requests, or repeatedly request data that is computationally expensive may result in secondary rate limiting.

Secondary rate limits are not intended to interfere with legitimate use of the 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/2.22/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 Recommendation、または 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 をデフォルトにする

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

タイムスタンプを指定できる API 呼び出しの場合、その正確なタイムスタンプを使用します。 これはコミット 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 呼び出しが行われた時のタイムスタンプが生成されます。 たとえば、コンテンツ API は追加または変更ごとに git コミットを生成し、タイムスタンプとして現在の時刻を使用します。 このヘッダは、現在のタイムスタンプの生成に使用されたタイムゾーンを決定します。

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

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

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

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