Skip to main content

REST API のリソース

GitHub Enterprise Server APIが提供するリソースにアクセスする方法を学んでください。

公式の GitHub Enterprise Server 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.6.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

注: GitHub では、Authorization ヘッダを使用して OAuth トークンを送信することをお勧めしています。

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

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

OAuth2 キー/シークレット

非推奨の注意: GitHub では、クエリ パラメーターを使った API の認証が廃止されます。 API の認証は、HTTP 基本認証を使って行う必要があります。 スケジュールされたブラウンアウトなど、詳しい情報については、ブログの投稿を参照してください。

クエリ パラメーターを使った API の認証は、利用はできるものの、セキュリティ上の懸念からサポートされなくなりました。 代わりに、client_id、または client_secret のアクセス トークンをヘッダーに移動することをインテグレーターにお勧めします。 GitHubは、クエリパラメータによる認証の削除を、事前に通知します。

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

client_idclient_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.6/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.6/rest"
> }

パラメーター

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

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

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

POSTPATCHPUTDELETE の要求については、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入力が無効です。

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

HTTP リダイレクト

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

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

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

HTTP 動詞

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

動詞説明
HEADHTTP ヘッダ情報のみを取得するために、任意のリソースに対して発行できます。
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"

改ページ位置の自動修正

複数の項目を返す要求は、既定では 30 項目ごとにページ分けされます。 page パラメーターを使用すると、さらにページを指定できます。 一部のリソースでは、per_page パラメーターを使用してカスタム ページ サイズを最大 100 に設定することもできます。 技術的な理由から、すべてのエンドポイントで per_page パラメーターが考慮されるわけではないことに注意してください。たとえば、イベントを参照してください。

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

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

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

改ページ位置の詳細については、「改ページ位置を使用した走査」に関するガイドを参照してください。

: 独自の URL を作成するのではなく、Link ヘッダー値を使用して呼び出しを形成することが重要です。

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 つ以上の Hypermedia リンク関係が含まれており、その一部は URI テンプレートとして展開が必要な場合があります。

取りうる可能性のある rel の値は次のようになります。

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

Timeouts

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

{
    "message": "Server Error"
}

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

レート制限

your GitHub Enterprise Server instanceへの様々な種類のAPIリクエストは、様々なレート制限に従います。

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

: 次のレート制限は、GitHub Enterprise Server の既定のレート制限です。 your GitHub Enterprise Server instance のレート制限を確認するには、サイト管理者に問い合わせてください。

: 現在のレート制限の状態はいつでも確認できます。 詳細については、「レート制限のステータスのチェック」を参照してください。

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

個人アクセストークンで認証された直接のAPIリクエストは、user-to-serverリクエストです。 OAuth AppあるいはGitHub Appは、ユーザが認可した後、user-to-serverリクエストをユーザの代わりに発行することもできます。 詳細については、「個人用アクセス トークンの作成」、「OAuth アプリの承認」、「GitHub アプリの承認」を参照してください。

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-limit1 時間あたりのリクエスト数の上限。
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.6/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.6/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 呼び出しのタイムゾーン情報を決定する際に、優先順位に従って次のルールを適用します。

これらのルールは、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 コミットを作成します。