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

GitHub の GraphQL API についての情報は、v4 ドキュメントを参照してください。 GraphQL への移行についての情報は、「REST から移行する」を参照してください。

スキーマ

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

$ curl -I http(s)://[hostname]/api/v3/users/octocat/orgs

> HTTP/1.1 200 OK
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> Status: 200 OK
> 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.20.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/1.1 401 Unauthorized

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

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

$ curl -i http(s)://[hostname]/api/v3 -u -u valid_username:valid_password 
> HTTP/1.1 403 Forbidden
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/enterprise/2.20/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":["public_repo"]}' 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/1.1 400 Bad Request
   Content-Length: 35
   
   {"message":"Problems parsing JSON"}
   

2. 間違ったタイプの JSON 値を送信すると、400 Bad Request レスポンスが返されます。

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

3. 無効なフィールドを送信すると、422 Unprocessable Entity レスポンスが返されます。

   HTTP/1.1 422 Unprocessable Entity
   Content-Length: 149
   
   {
     "message": "Validation Failed",
     "errors": [
       {
         "resource": "Issue",
         "field": "title",
         "code": "missing_field"
       }
     ]
   }
   

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

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

HTTP リダイレクト

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

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

HTTP メソッド

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

ハイパーメディア

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

次に、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 パラメータを使用して結果の中を移動できます。

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

リンクヘッダ

Link ヘッダには、ページネーション情報が含まれています。 例:

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

この Link レスポンスヘッダには、1 つ以上のハイパーメディアリンク関係が含まれています。その一部には、URI テンプレートとしての拡張が必要な場合があります。

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

レート制限

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

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

Note that the limits mentioned above are the default rate limits for GitHub Enterprise Server の Enterprise 設定を使用してアナウンスバナーを設定することもできます。 Contact your site administrator to confirm if rate limits are enabled and how they are configured.

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

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

$ curl -I http(s)://[hostname]/api/v3/users/octocat
> HTTP/1.1 200 OK
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> Status: 200 OK
> X-RateLimit-Limit: 60
> X-RateLimit-Remaining: 56
> X-RateLimit-Reset: 1372700873

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

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

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

> HTTP/1.1 403 Forbidden
> Date: Tue, 20 Aug 2013 14:50:41 GMT
> Status: 403 Forbidden
> 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.20/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/1.1 200 OK
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> Status: 200 OK
> X-RateLimit-Limit: 5000
> X-RateLimit-Remaining: 4966
> X-RateLimit-Reset: 1372700873

レート制限内に収める

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

不正利用レート制限

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

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

アプリケーションがこのレート制限をトリガーすると、次のような有益なレスポンスを受け取ります。

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

> {
>   "message": "You have triggered an abuse detection mechanism and have been temporarily blocked from content creation. Please retry your request again later.",
>   "documentation_url": "https://docs.github.com/enterprise/2.20/rest/overview/resources-in-the-rest-api#abuse-rate-limits"
> }

条件付きリクエスト

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

$ curl -I http(s)://[hostname]/api/v3/user
> HTTP/1.1 200 OK
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Status: 200 OK
> 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/1.1 304 Not Modified
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Status: 304 Not Modified
> 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/1.1 304 Not Modified
> Cache-Control: private, max-age=60
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Status: 304 Not Modified
> 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/1.1 302 Found
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/1.1 204 No Content
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 コミットを作成します。