1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
## GitHub API v3
**Note:** This API is in a beta state. Breaking changes may occur.
### Schema
All API access is over HTTPS, and accessed from the `api.github.com`
domain. All data is sent and received as JSON.
Blank fields are included as `null` instead of being omitted.
All timestamps are returned in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
### Authentication
There are two ways to authenticate through GitHub API v3:
Basic Authentication:
$ curl -u "username:PASSWORD" https://api.github.com
OAuth2 Token (sent in a header):
$ 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](http://develop.github.com).
### Pagination
Requests that return multiple items will be paginated to 30 items by
default. You can specify further pages with the `?page` parameter. You
can also set a custom page size up to 100 with the `?per_page` parameter.
$ curl https://api.github.com/repos.json?page=2&per_page=100
### Rate Limiting
We limit requests to API v3 to 5000 per day. This is keyed off either your login, or your request IP. You can check the returned HTTP headers to see your current status:
$ curl -i https://api.github.com
HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4966
You can file a [support issue](http://support.github.com/dashboard/queues/2386-api) to request white listed access for your application. We prefer sites that setup OAuth applications for their users.
### JSON-P Callbacks
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 responses always return 200, and are wrapped in meta
objects containing the actual meta information:
$ curl https://api.github.com?callback=foo
foo({
"data": {},
"meta": {
"status": 200,
"pagination": {"page": 1, "per_page": 30},
"rate": {"key": "IP ADDRESS", "remaining": 4999, "limit": 5000}
}
})
### Versions
Api V3 uses content negotiation to specify the expected output format.
V3 is specified with this mime type:
application/vnd.github.v3+json
This allows us to upgrade the API if needed, and support multiple versions of the API in transition period. If you want to ensure your API usage works uninterrupted, you will want to specify this mime type in an Accept header:
curl -H "Accept: application/vnd.github.v3+json" https://api.github.com
Specifying `application/json` will assume the latest version of the API. Specifying an unknown version will result in a `406 Not Acceptable` error.
We don't plan to bump the API version unless absolutely necessary. Things like removing end points, renaming or removing object attributes, or removing resources completely will result in a new version. This should be extremely rare, however.
|
