Github API v3 -Overview

Overview 概观

This describes the resources that make up the official GitHub API v3. If you have any problems or requests please contact support.

下面是官方GitHub API v3.组成资源的描述，如果你有任何问题或者请求，请联系网站的支持方

• Current Version
• Schema
• Parameters
• Root Endpoint
• Client Errors
• HTTP Redirects
• HTTP Verbs
• Authentication
• Hypermedia
• Pagination
• Rate Limiting
• User Agent Required
• Conditional requests
• Cross Origin Resource Sharing
• JSON-P Callbacks
• Timezones

Current Version

By default, all requests receive the v3 version of the API. We encourage you to explicitly request this version via the Accept header.

默认情况下，所有的请求收到的回复都是api的v3版本的，我们鼓励你在请求头中明确的指出这个版本

Accept: application/vnd.github.v3+json

Schema

All API access is over HTTPS, and accessed from the api.github.com domain (or through yourdomain.com/api/v3/ for enterprise). All data is sent and received as JSON.

所有的api访问都必须是是通过https和api.github.com域名（或者个人企业通过 yourdomain.com/api/v3/ ），所有的数据发送和接受都是JSON格式的。

$ curl -i https://api.github.com/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
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
X-GitHub-Media-Type: github.v3
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1350085394
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff

[]

Blank fields are included as null instead of being omitted.

其中的空白的字段是null而不是被省略的意思

All timestamps are returned in ISO 8601 format:

所有的时间戳都是按照ISO 8601标准返回的

YYYY-MM-DDTHH:MM:SSZ

Summary Representations

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the “summary” representation of the resource. (Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the “detailed” representation.)

Example: When you get a list of repositories, you get the summary representation of each repository. Here, we fetch the list of repositories owned by the octokit organization:

当你拉取的一个资源列表，这个响应包含的是一个资源属性的子集，这是一个资源的简略描述。（一些api提供的属性是相当长的。考虑到效率的因素，简要的描述省略了这些属性，想要获取这些属性，请获取详细的描述）

Example: When you get a list of repositories, you get thesummary representation of each repository. Here, we fetch the list ofrepositories owned by the octokit organization:

举个例子，当你得到一个仓库的列表，你得到的是每个仓库的简要描述，下面代码，我们拉取一个属于octokit 组织的仓库列表，见下面。

GET /orgs/octokit/repos

Detailed Representations

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the “detailed” representation of the resource. (Note that authorization sometimes influences the amount of detail included in the representation.)

Example: When you get an individual repository, you get the detailed representation of the repository. Here, we fetch the octokit/octokit.rb repository:

当你拉取一个个人的资源，这种有标志的响应包括了这个资源的所有属性，这就是资源的详细描述。（请注意，授权认证有时会影响你目前获得详细信息的数量）

举个例子：当你拉去一个个人的仓库，你会得到仓库详细的描述信息表达，看下面，我们拉去了 octokit/octokit.rb的个人仓库代码。

GET /repos/octokit/octokit.rb

The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method.

这个文件提供了每一个API方法的响应例子，例子的响应详细的描述的方法的返回值所有属性。

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

很多的api方法提供可选择的参数，对于get请求，没有被指定为地址中的一段的任何参数，可以当做http的查询字符串访问成功。

$ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"

In this example, the ‘vmg’ and ‘redcarpet’ values are provided for the :owner and :repoparameters in the path while :state is passed in the query string.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’:

在这个例子中，‘vmg’’和‘redcarpet’’的意思是提供了所有者的名字和仓库的名字，然而在路径中的参数state 是作为查询字符串被接受的。

对于POST, PATCH, PUT,和 DELETE请求，参数不应该包含在URL中，应该编码为JSON作为application/json的值。

$ curl -i -u username -d '{"scopes":["public_repo"]}' https://api.github.com/authorizations

Root Endpoint

You can issue a GET request to the root endpoint to get all the endpoint categories that the API supports:

你可以发送一个请求到根节点去获得所有api支持端点的类别。

$ curl https://api.github.com

Note that for GitHub Enterprise, as with all other endpoints, you’ll need to pass in your GitHub Enterprise endpoint as the hostname, as well as your username and password:

请注意，对于github企业，和所有的端点一样，你需要通过你的主机名，用户名，密码来访问github的企业端点。

$ curl https://hostname/api/v3/ -u username:password

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

在客户端请求后的返回体中，可能有下面三种类型错误。

1. Sending invalid JSON will result in a 400 Bad Request response.

    HTTP/1.1 400 Bad Request
    Content-Length: 35
   
    {"message":"Problems parsing JSON"}
   

2. 发送了无效的JSON，会得到 400 Bad Request响应

   
   

3. Sending the wrong type of JSON values will result in a 400 Bad Request response.

   发送了错误的JSON类型值，会返回400 Bad Request响应

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

4. Sending invalid fields will result in a 422 Unprocessable Entity response.

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

5. 发送了无效的字段，会返回422Unprocessable Entity（错误实体）响应。

   
   

All error objects have resource and field properties so that your client can tell what the problem is. There’s also an error code to let you know what is wrong with the field. These are the possible validation error codes:

所有的错误对象都有资源和字段属性，这样你就可以告诉你的客户端出现了什么问题。这里也有一些错误码，让你知道你的字段哪里出现了所悟，下面是可能出现的正确错误码。

Error Name	Description
missing 没有找到	This means a resource does not exist.这意味着你请求的资源不存在
missing_field 没有找到字段	This means a required field on a resource has not been set 这意味着这个请求需要的字段你没有设置.
invalid 无效的	This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information 这意味着字段的格式是无效的，这个资源的文件应该给你更多详细的信息.
already_exists 已经存在	This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names) 这意味着其他的资源有相同的字段值，通常发生在资源有单一的key的时候（例如标签的的名字）.

If resources have custom validation errors, they will be documented with the resource.

如果资源有自定义验证错误，资源中会备有证明文件

HTTP Redirects

API v3 uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

API v3在合适的地方使用HTTP重定向，客户端应该呈现任何的请求都可能被结果重定向。收到了重定向不是一个错误，客户端应该跟随这个重定向。重定向的响应头会有一个Location 字段，这个字段包含了资源的URL，客户端应该重复这个这个请求。 

Status Code	Description
301	Permanent redirection. The URI you used to make the request has been superseded by the one specified in the Location header field. This and all future requests to this resource should be directed to the new URI 永久重定向，你请求的URL已经被一个在Location 头中的指定的字段取代了，这个资源的这个请求和以后所有的请求都应该被重定向到新的URL.
302,307	Temporary redirection. The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests 临时的重定向：URL请求应该逐字重复Location 头中指定的子段，但是对于以后的请求，客户端应该继续使用原始的URL。.

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

其他的重定向状态码请和HTTP 1.1细则使用保持一致

HTTP Verbs

Where possible, API v3 strives to use appropriate HTTP verbs for each action.

在所有可能的地方，API v3努力对每一个请求使用合适的超文本传输协议

Verb	Description
HEAD	Can be issued against any resource to get just the HTTP header info. 你可以得到已经发布的任何资源的头信息
GET	Used for retrieving resources 被用于检索资源.
POST	Used for creating resources, or performing custom actions (such as merging a pull request) 用于建立资源，或者执行用户动作（例如合并推送请求）.
PATCH	Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests 用于更新局部的JSON资源，举个例子，一个发布的资源有标题和内容属性，.PATCH请求可以接受一个或者多个更新资源的属性，PATCH是一个相对新的不常用的超文本传输协议，所以资源端点也接受POST请求。
PUT	Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero 被用于.替换资源或集合，put请求没有请求体，请确认使用的时候设置了 Content-Length为0.
DELETE	Used for deleting resources 用于删除资源.

Authentication 授权

There are three ways to authenticate through GitHub API v3. Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private repositories to unauthorized users.

要使用GitHub API v3.这里有三种方式获取授权。如果美哦与授权，需要验证的请求会返回404而不是403.在有些地方，这么做是为了阻止泄露私人的仓库给未授权的用户

Basic Authentication

基本的授权

$ curl -u "username" https://api.github.com

OAuth2 Token (sent in a header)

OAuth2 Token（在消息头发送）

$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com

OAuth2 Token (sent as a parameter)（作为消息发送）

$ curl https://api.github.com/?access_token=OAUTH-TOKEN

Read more about OAuth2. Note that OAuth2 tokens can be acquired programmatically, for applications that are not websites.

请去了解更多关于OAuth2，请注意 OAuth2 令牌 可以以编程的方式获得，并不只是网站的应用程序。

OAuth2 Token

OAuth2 Key/Secret

$ curl 'https://api.github.com/users/whatever?client_id=xxxx&client_secret=yyyy'

This should only be used in server to server scenarios. Don’t leak your OAuth application’s client secret to your users. Read more about unauthenticated rate limiting.

这样的请求只用于服务器到服务器的情况，不要泄露你的认证程序客户端密保给你的用户，点击这里了解更多关于未授权的速率限制。

Failed login limit 登陆失败的限制

Authenticating with invalid credentials will return 401 Unauthorized:

无效的认证证书将会返回401错误

$ curl -i https://api.github.com -u foo:bar

HTTP/1.1 401 Unauthorized

{
  "message": "Bad credentials",
  "documentation_url": "https://developer.github.com/v3"
}

After detecting several requests with invalid credentials within a short period, the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with 403 Forbidden:

在一段很短的时间内检索到大量的无效的的证书，API会通过返回403临时的拒绝这个用户的所有认证请求（其中包括有效的证书）

$ curl -i https://api.github.com -u valid_username:valid_password

HTTP/1.1 403 Forbidden

{
  "message": "Maximum number of login attempts exceeded. Please try again later.",
  "documentation_url": "https://developer.github.com/v3"

Hypermedia 超媒体

All resources may have one or more *_url properties linking to other resources. These are meant to provide explicit URLs so that proper API clients don’t need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers. All URLs are expected to be proper RFC 6570 URI templates.

You can then expand these templates using something like the uri_template gem:

所有的资源都有一个*_url的属性去连接其他的资源，也就意味着我们提供一个明确的URLs，这样合适的api客户就不需要自己构造api了，我们强烈建议api的客户去

这样做，这么做对于开发者来说以后的api升级将会更容易。所有的URLs我们希望遵循RFC 6570 URL模板标准

你可以使用像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"

Pagination 标记页码

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter, see events for example.

如果一个请求会放回大量的项目，我们将会默认标记每页30个，你可以指定要访问的页码通过?page参数，对于一些资源你也可以自己设置一些每页显示的数量，最大可以设置到100，通过 ?per_page参数。请注意因为技术的原因，并不是所

有的端点接受?per_page参数，请看实例：

$ curl 'https://api.github.com/user/repos?page=2&per_page=100'

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

For more information on pagination, check out our guide on Traversing with Pagination.

请注意，页码的数量是从1开始的，省略了?page参数，返回的页码将会从1开始

想获取更多关于页码标记的信息，请查看我们的在遍历与分页的引导。

Link Header  链接报头

The pagination info is included in the Link header. It is important to follow these Link header values instead of constructing your own URLs. In some instances, such as in the Commits API, pagination is based on SHA1 and not on page number.

页码标记信息被包含在链接报头中，跟随这个链接报头的值而不是构造你自己的URLs是非常重要的。在某些情况下，例如在commit的api中，页码标记是基于SHA1 不是页码数量。

Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next",
  <https://api.github.com/user/repos?page=50&per_page=100>; rel="last"

Linebreak is included for readability.

可读性包含了Linebreak 

The possible rel values are:

可能的rel：

Name	Description
next	Shows the URL of the immediate next page of results 马上要显示的下一页结果的url.
last	Shows the URL of the last page of results 最后一页结果的url.
first	Shows the URL of the first page of results 第一页结果的url.
prev	Shows the URL of the immediate previous page of results 马上要显示的前一页结果的url.

Rate Limiting 关于访问的速率限制

For requests using Basic Authentication or OAuth, you can make up to 5,000 requests per hour. For unauthenticated requests, the rate limit allows you to make up to 60 requests per hour. Unauthenticated requests are associated with your IP address, and not the user making requests. Note that the Search API has custom rate limit rules.

对于使用基本的验证和授权的请求，你大约可以每小时发送5000次请求。对于没有认证的请求，因为速率限制，你只能每小时接近发送60次请求。没有验证的请求限制速率和你的IP有关系，而和你的用户名没有关系（这里也就是说，你同一个用户换一个IP就可以继续访问了）。注意，请搜索API速率限制的相关规则，做详细的了解。

You can check the returned HTTP headers of any API request to see your current rate limit status:

你可以通过核对请求API的http响应头来查看你的当前的速率限制状态。

$ curl -i https://api.github.com/users/whatever

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

The headers tell you everything you need to know about your current rate limit status:

响应头会告诉你关于你当前速率限制状态的所有事

Header Name响应头	Description 描述
X-RateLimit-Limit	The maximum number of requests that the consumer is permitted to make per hour. 这个的意思是：当前用户每小时允许的最大请求数量
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window. 这个的意思是：当前速率窗口（ip）剩余的请求访问数量
X-RateLimit-Reset	The time at which the current rate limit window resets in UTC epoch seconds. 这个的意思是：当前速率窗口的时间被重置为UTC时代秒（这个我也没明白！！！）

If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.

如果你需要不同格式的时间，任何现在流行的编程语言都可以获取到。举个例子，如果你打开web浏览器的控制台，你可以很容易得到一个重置时间的对象。（然后就可以操作了）

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

Once you go over the rate limit you will receive an error response:

一旦你超过了速率限制，你会收到一条错误的效应消息。（下面就是）

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://developer.github.com/v3/#rate-limiting"
}

You can also check your rate limit status without incurring an API hit. 

你可以查看你的速录限制而不引发另一个API请求

Increasing the unauthenticated rate limit for OAuth applications

为没授权的认证程序提高访问速率

If your OAuth application needs to make unauthenticated calls with a higher rate limit, you can pass your app’s client ID and secret as part of the query string.

如果你的认证程序需要更高的未授权请求速率。你可以通过把你的客户端ID和密保放在请求的查询字符串的地方来通过高速率验证。

$ curl -i 'https://api.github.com/users/whatever?client_id=xxxx&client_secret=yyyy'

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

This method should only be used for server-to-server calls. You should never share your client secret with anyone or include it in client-side browser code.

这种方法应该只用于服务器和服务器之间的交互，你永远都不要和别人分享你的用户密保包括在客户端浏览的代码。

Staying within the rate limit

保持速率限制

If you are using Basic Authentication or OAuth, and you are exceeding your rate limit, you can likely fix the issue by caching API responses and using conditional requests.

如果你使用基本的授权或者认证，你又想超过现在的速率限制，你可能需要用过缓存API响应和使用条件请求来解决这个问题。

If you’re using conditional requests and still exceeding your rate limit, please contact us to request a higher rate limit for your OAuth application.

如果你使用条件请求还是超过了你的速率限制，请联系我们，请求为你的认证的程序开通更高的速率限制。

User Agent Required

用户代理的必须条件

All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected. We request that you use your GitHub username, or the name of your application, for the User-Agent header value. This allows us to contact you if there are problems.

所有的API请求必须包含有效的User-Agent头，没有User-Agent头的请求将会被拒绝。我们需要你的 User-Agent请求头的值包含你的GitHub用户名或者你程序的名字，这样如果有任何

问题我们可以联系到你

Here’s an example:

这里有一个例子

User-Agent: Awesome-Octocat-App

If you provide an invalid User-Agent header, you will receive a 403 Forbidden response:

如果你提供了一个无效的User-Agent 头，一会收到一个403 Forbidden 响应

$ curl -iH 'User-Agent: ' https://api.github.com/meta
HTTP/1.0 403 Forbidden
Connection: close
Content-Type: text/html

Request forbidden by administrative rules.
Please make sure your request has a User-Agent header.
Check https://developer.github.com for other possible causes.

Conditional requests

请求条件

Most responses return an ETag header. Many responses also return a Last-Modified header. You can use the values of these headers to make subsequent requests to those resources using the If-None-Match and If-Modified-Since headers, respectively. If the resource has not changed, the server will return a 304 Not Modified. Also note: making a conditional request and receiving a 304 response does not count against your Rate Limit, so we encourage you to use it whenever possible.

大多数请求会返回一个ETag 的报文头，很多请求也返回一个Last-Modified的报文头，你可以使用这些报文头的值包括If-None-Match和If-Modified-Since报文头去

进行随后的请求以获取资源。但是，如果请求的资源没有改变，服务器会返回304 Not Modified。还要注意：发一个条件请求收到了304响应，不计入

你的速率限制，所以我们鼓励你在任何可能的地方使用它。

$ curl -i https://api.github.com/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 https://api.github.com/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 https://api.github.com/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

Cross Origin Resource Sharing 跨域资源分享

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.

我们的API支持来自任何源的ajax请求的资源跨域分享，关于详细内容，你可以阅读CORS W3C Recommendation，或者HTML 5 安全引导的简介。

Here’s a sample request sent from a browser hitting http://example.com:

下面是一个在浏览器地址栏输入http://example.com请求的实例。

$ curl -i https://api.github.com -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
Access-Control-Allow-Credentials: true

This is what the CORS preflight request looks like:

跨域请求前准备工作，就像下面这样。

$ curl -i https://api.github.com -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
Access-Control-Allow-Credentials: true

JSON-P Callbacks

JSON-P回调

You can send a callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed GitHub content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.

你可以发送任何包含一个callback参数的GET请求，这样你就可以得到一个JSON函数格式包裹的结果，当浏览器想通过在一个页面置入一个跨个人域名的HitGub内容时，这是一个典型的应用。

$ curl https://api.github.com?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://api.github.com?page=2", {"rel": "next"}]
    ]
  },
  "data": {
    // the data
  }
})

You can write a JavaScript handler to process the callback. Here’s a minimal example you can try out:

你可以写一个JS的处理程序去处理返回的内容。下面是是一个小例子，你可以试一试。

<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://api.github.com?callback=foo';

document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>

<body>
  <p>Open up your browser's console.</p>
</body>
</html>

All of the headers are the same String value as the HTTP Headers with one notable exception: Link. Link headers are pre-parsed for you and come through as an array of [url, options] tuples.

所有的头都是相同的字符串值，作为HHP头有一个例外：link，link头被提前解析了，你会作为[url, options]这样的格式收到

A link that looks like this:

所有的link看起来像下面这样

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

… will look like this in the Callback output:

会变成下下面这样返回

{
  "Link": [
    [
      "url1",
      {
        "rel": "next"
      }
    ],
    [
      "url2",
      {
        "rel": "foo",
        "bar": "baz"
      }
    ]
  ]
}

Timezones 时区

Some requests allow for specifying timestamps or generate timestamps with time zone information. We apply the following rules, in order of priority, to determine timezone information for API calls.

一些请求允许你指定一个时间戳或者以时区信息生成一个时间戳，我们遵循以下规则，按优先级排序，决定API调用的时区信息。

Explicitly provide an ISO 8601 timestamp with timezone information

请确定提供的时区信息是一个ISO 8601的时间戳

For API calls that allow for a timestamp to be specified, we use that exact timestamp. An example of this is the Commits API.

API调用允许指定一个时间戳，我们会正确的使用这个时间戳，一个实用的例子就是Commit API.

These timestamps look something like 2014-02-27T15:05:06+01:00. Also see this example for how these timestamps can be specified.

这些时间戳像2014-02-27T15:05:06+01:00一样的格式，  请点击这里（this example）查看这些时间戳是怎么被指定的。

Using the Time-Zone header 使用Time-Zone查看报文头

It is possible to supply a Time-Zone header which defines a timezone according to the list of names from the Olson database.

提供一个 根据OIson数据集名字列表定义的时区的Time-Zone 的报文头是可以的。

$ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github/linguist/contents/new_file.md

This means that we generate a timestamp for the moment your API call is made in the timezone this header defines. For example, the Contents API generates a git commit for each addition or change and uses the current time as the timestamp. This header will determine the timezone used for generating that current timestamp.

这个意思是我们生成一个暂时的时间戳，在你的API调用时的时区定义。举个例子，提交内容API用当前时间生成一个每一次提交或改变的时间戳。这个头会决定用于生成时间戳的时区。

Using the last known timezone for the user

为用户使用最后一个已知的时区

If no Time-Zone header is specified and you make an authenticated call to the API, we use the last known timezone for the authenticated user. The last know timezone is updated whenever you browse the GitHub.com website.

如果没有Time-Zone 报文头被指定，而且你还使用了已经认证的调用请求，我们会对已经认证的用户使用最后一个已知时区。最后一个已知时区会在你浏览

GitHub.com 网站的时候更新。

UTC 世界时间代码

If the steps above don’t result in any information, we use UTC as the timezone to create the git commit.

如果上面的步骤没有任何结果信息，我们会使用 世界时间代码作为提交的时区信息。