REST API のリソース

スキーマ

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

$ curl -I https://<em>HOSTNAME</em>/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://<em>HOSTNAME</em>/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://<em>HOSTNAME</em>/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://<em>HOSTNAME</em>/api/v3/authorizations

ルートエンドポイント

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

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

GraphQL グローバルノード ID

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

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"

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

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

$ curl -I https://<em>HOSTNAME</em>/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://<em>HOSTNAME</em>/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://<em>HOSTNAME</em>/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://<em>HOSTNAME</em>/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://<em>HOSTNAME</em>/api/v3/repos/github-linguist/linguist/contents/new_file.md

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

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

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

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

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

REST API のリソース

この記事の内容