forked from github/developer.github.com
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
409 lines (363 loc) · 17 KB
/
Copy pathindex.html
File metadata and controls
409 lines (363 loc) · 17 KB
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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en-us" />
<meta http-equiv="imagetoolbar" content="false" />
<meta name="MSSmartTagsPreventParsing" content="true" />
<title>Versions | GitHub API</title>
<link rel="alternate" type="application/atom+xml" title="API Changes" href="/changes.atom" />
<link href="/css/reset.css" rel="stylesheet" type="text/css" />
<link href="/css/960.css" rel="stylesheet" type="text/css" />
<link href="/css/uv_active4d.css" rel="stylesheet" type="text/css" />
<link href="/shared/css/documentation.css" media="screen" rel="stylesheet" type="text/css">
<link href="/shared/css/pygments.css" media="screen" rel="stylesheet" type="text/css">
<script src="/shared/js/jquery.js" type="text/javascript"></script>
<script src="/shared/js/documentation.js" type="text/javascript"></script>
</head>
<body class="api">
<div id="header-wrapper">
<div id="header">
<div>
<a class="logo" href="/">GitHub:Developer</a>
<ul class="nav">
<li><a href="/" class="nav-overview">Overview</a></li>
<li><a href="/v3/" class="nav-api">API</a></li>
<li><a href="/changes/" class="nav-blog">Blog</a></li>
<li><a href="https://github.com/contact">Support</a></li>
<li id="search-container">
<input type="text" id="searchfield" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" /><label class="search-placeholder">Search</label>
<div class="cancel-search"></div>
<ul id="search-results">
</ul>
</li>
</ul>
</div>
</div><!-- #header -->
</div><!-- #header-wrapper -->
<div class="sub-nav">
<h2><a href="/v3/">API</a></h2>
<ul>
<li><a href="/v3/" class="active">Documentation</a></li>
<li><a href="/guides/">Guides</a></li>
<li><a href="/libraries/">Libraries</a></li>
</ul>
</div>
<div id="wrapper">
<div class="content">
<h1 id="versions">Versions</h1>
<p>There are two stable versions of the GitHub API: <a href="#beta">beta</a> and <a href="#v3">v3</a>. There are just a few <a href="#differences-from-beta-version">differences between these two versions</a>.</p>
<p>By default, all requests receive the beta version. Soon, v3 will become the default version. (Check out the <a href="/changes/2014-01-07-upcoming-change-to-default-media-type/">blog post</a> for details.) We encourage you to <a href="/v3/media/#beta-v3-and-the-future">request a specific version via the <code>Accept</code> header</a>.</p>
<h1 id="v3">v3</h1>
<p>The <a href="/v3">v3 API</a> is stable and unchangeable. Please <a href="https://github.com/contact?form%5Bsubject%5D=APIv3">file a support issue</a> if you have problems.</p>
<p>Some v3 functionality is <a href="#v3-deprecations">deprecated</a> and will be removed in the next major version of the API.</p>
<h2 id="differences-from-beta-version">Differences from beta version</h2>
<p>The v3 media type differs from the beta media type in just a few places:</p>
<h3 id="gist-json">Gist JSON</h3>
<p>For <a href="/v3/gists/#get-a-single-gist">Gists</a>, the v3 media type renames the <code>user</code> attribute to <code>owner</code>.</p>
<h3 id="issue-json">Issue JSON</h3>
<p>When an <a href="/v3/issues/#get-a-single-issue">issue</a> is not a pull request, the v3 media type omits the <code>pull_request</code> attribute.</p>
<h3 id="repository-json">Repository JSON</h3>
<p>For <a href="/v3/repos/#get">Repositories</a>, the v3 media type omits the <code>master_branch</code> attribute. API clients should use the <code>default_branch</code> attribute to obtain the repository’s default branch.</p>
<h3 id="user-emails-json">User Emails JSON</h3>
<p>For <a href="/v3/users/emails/#list-email-addresses-for-a-user">User Emails</a>, the v3 media type returns an array of hashes (instead of an array of strings).</p>
<h2 id="v3-deprecations">v3 deprecations</h2>
<p>The following functionality is deprecated. For backwards compatibility purposes,
v3 will continue to provide this functionality. However, this deprecated
functionality <em>will be removed</em> in the next major version of the API.</p>
<p>The recommendations below will help you prepare your application for the next major version of the API.</p>
<ol>
<li>
<dl>
<dt>Method: /gists/:id/fork</dt>
<dd>Recommendation: Use <strong>/gists/:id/forks</strong> (plural) instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Method: /legacy/issues/search/:owner/:repository/:state/:keyword</dt>
<dd>Recommendation: Use <a href="/v3/search/#search-issues">v3 Issue Search API</a> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Method: /legacy/repos/search/:keyword</dt>
<dd>Recommendation: Use <a href="/v3/search/#search-repositories">v3 Repository Search API</a> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Method: /legacy/user/search/:keyword</dt>
<dd>Recommendation: Use <a href="/v3/search/#search-users">v3 User Search API</a> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Method: /legacy/user/email/:email</dt>
<dd>Recommendation: Use <a href="/v3/search/#search-users">v3 User Search API</a> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Method: /repos/:owner/:repo/hooks/:id/test</dt>
<dd>Recommendation: Use <strong>/repos/:owner/:repo/hooks/:id/tests</strong> (plural) instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Query parameters when POSTing to /repos/:owner/:repo/forks</dt>
<dd>Recommendation: Use JSON to POST to this method instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Query parameter value: Passing “watchers” as the value for the “sort” parameter in a GET request to /repos/:owner/:repo/forks</dt>
<dd>Recommendation: Use <strong>stargazers</strong> as the value instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Pull Request attribute: merge_commit_sha</dt>
<dd>Recommendation: <a href="/changes/2013-04-25-deprecating-merge-commit-sha/">Do not use this attribute</a>.</dd>
</dl>
</li>
<li>
<dl>
<dt>Rate Limit attribute: rate</dt>
<dd>Recommendation: Use <strong>resources[“core”]</strong> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Repository attribute: forks</dt>
<dd>Recommendation: Use <strong>fork_count</strong> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Repository attribute: master_branch</dt>
<dd>Recommendation: Use <strong>default_branch</strong> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Repository attribute: open_issues</dt>
<dd>Recommendation: Use <strong>open_issues_count</strong> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>Repository attribute: public</dt>
<dd>Recommendation: When <a href="/v3/repos/#create">creating a repository</a>, use the
<strong>private</strong> attribute to indicate whether the repository should be public or
private. Do not use the <strong>public</strong> attribute.</dd>
</dl>
</li>
<li>
<dl>
<dt>Repository attribute: watchers</dt>
<dd>Recommendation: Use <strong>watchers_count</strong> instead.</dd>
</dl>
</li>
<li>
<dl>
<dt>User attribute: bio</dt>
<dd>Recommendation: Do not use this attribute. It is obsolete.</dd>
</dl>
</li>
</ol>
<h1 id="beta">beta</h1>
<p>The <a href="/v3">beta API</a> is now stable and unchangeable. Please <a href="https://github.com/contact?form%5Bsubject%5D=APIv3">file a support issue</a> if you have problems.</p>
<p>Starting April 15, 2014, the <a href="/changes/2014-01-07-upcoming-change-to-default-media-type/">beta version will no longer be the <em>default</em> version</a>. However, we expect to continue supporting the beta version for a while. We will eventually retire the beta version, but we have no official retirement date to annouce at the moment. When the time comes, rest assured that we’ll announce the retirement with plenty of notice.</p>
<h2 id="breaking-beta-changes">Breaking beta changes</h2>
<h3 id="june-15th-2011">June 15th, 2011:</h3>
<ul>
<li>
<code>gravatar_url</code> is being deprecated in favor of <code>avatar_url</code> for all
responses that include users or orgs. A default size is no longer
included in the URL.</li>
<li>Creating new gists (both anonymously and with an authenticated user)
should use <code>POST /gists</code> from now on. <code>POST /users/:user/gists</code> is no
longer supported.</li>
</ul>
<h3 id="june-1st-2011">June 1st, 2011:</h3>
<ul>
<li>Removed support for PUT verb on update requests. Use POST or PATCH
instead.</li>
<li>Removed <code>.json</code> extension from all URLs.</li>
<li>No longer using the X-Next or X-Last headers. Pagination info is
returned in the Link header instead.</li>
<li>JSON-P response has completely changed to a more consistent format.</li>
<li>Starring gists now uses PUT verb (instead of POST) and returns 204.</li>
</ul>
<h1 id="v2">v2</h1>
<p>We removed support for API v2 on June 12, 2012.</p>
<h1 id="v1">v1</h1>
<p>We removed support for API v1 on June 12, 2012.</p>
</div>
<div id="js-sidebar" class="sidebar-shell">
<div class="js-toggle-list sidebar-module expandable">
<ul>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/">Overview</a></h3>
<ul class="js-guides">
<li><a href="/v3/media/">Media Types</a></li>
<li><a href="/v3/oauth/">OAuth</a></li>
<li><a href="/v3/auth/">Other Authentication Methods</a></li>
<li><a href="/v3/troubleshooting/">Troubleshooting</a></li>
<li><a href="/v3/versions/">Versions</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/activity/">Activity</a></h3>
<ul class="js-guides">
<li><a href="/v3/activity/events/">Events</a></li>
<li><a href="/v3/activity/events/types/">Event Types</a></li>
<li><a href="/v3/activity/feeds/">Feeds</a></li>
<li><a href="/v3/activity/notifications/">Notifications</a></li>
<li><a href="/v3/activity/starring/">Starring</a></li>
<li><a href="/v3/activity/watching/">Watching</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/gists/">Gists</a></h3>
<ul class="js-guides">
<li><a href="/v3/gists/comments/">Comments</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/git/">Git Data</a></h3>
<ul class="js-guides">
<li><a href="/v3/git/blobs/">Blobs</a></li>
<li><a href="/v3/git/commits/">Commits</a></li>
<li><a href="/v3/git/refs/">References</a></li>
<li><a href="/v3/git/tags/">Tags</a></li>
<li><a href="/v3/git/trees/">Trees</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/issues/">Issues</a></h3>
<ul class="js-guides">
<li><a href="/v3/issues/assignees/">Assignees</a></li>
<li><a href="/v3/issues/comments/">Comments</a></li>
<li><a href="/v3/issues/events/">Events</a></li>
<li><a href="/v3/issues/labels/">Labels</a></li>
<li><a href="/v3/issues/milestones/">Milestones</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/misc/">Miscellaneous</a></h3>
<ul class="js-guides">
<li><a href="/v3/emojis/">Emojis</a></li>
<li><a href="/v3/gitignore/">Gitignore</a></li>
<li><a href="/v3/markdown/">Markdown</a></li>
<li><a href="/v3/meta/">Meta</a></li>
<li><a href="/v3/rate_limit/">Rate Limit</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/orgs/">Organizations</a></h3>
<ul class="js-guides">
<li><a href="/v3/orgs/members/">Members</a></li>
<li><a href="/v3/orgs/teams/">Teams</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/pulls/">Pull Requests</a></h3>
<ul class="js-guides">
<li><a href="/v3/pulls/comments/">Review Comments</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/repos/">Repositories</a></h3>
<ul class="js-guides">
<li><a href="/v3/repos/collaborators/">Collaborators</a></li>
<li><a href="/v3/repos/comments/">Comments</a></li>
<li><a href="/v3/repos/commits/">Commits</a></li>
<li><a href="/v3/repos/contents/">Contents</a></li>
<li><a href="/v3/repos/keys/">Deploy Keys</a></li>
<li><a href="/v3/repos/deployments/">Deployments</a></li>
<li><a href="/v3/repos/downloads/">Downloads</a></li>
<li><a href="/v3/repos/forks/">Forks</a></li>
<li><a href="/v3/repos/hooks/">Hooks</a></li>
<li><a href="/v3/repos/merging/">Merging</a></li>
<li><a href="/v3/repos/releases/">Releases</a></li>
<li><a href="/v3/repos/statistics/">Statistics</a></li>
<li><a href="/v3/repos/statuses/">Statuses</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/search/">Search</a></h3>
<ul class="js-guides">
<li><a href="/v3/search/#search-repositories">Repositories</a></li>
<li><a href="/v3/search/#search-code">Code</a></li>
<li><a href="/v3/search/#search-issues">Issues</a></li>
<li><a href="/v3/search/#search-users">Users</a></li>
<li><a href="/v3/search/legacy/">Legacy Search</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/users/">Users</a></h3>
<ul class="js-guides">
<li><a href="/v3/users/emails/">Emails</a></li>
<li><a href="/v3/users/followers/">Followers</a></li>
<li><a href="/v3/users/keys/">Public Keys</a></li>
</ul>
</li>
</ul>
</div> <!-- /sidebar-module -->
<div class="sidebar-module notice">
<p>This website is a <a href="https://github.com/github/developer.github.com" target="_blank">public GitHub repository</a>. Please help us by forking the project and adding to it.</p>
</div>
<div class="sidebar-module api-status"><a href="https://status.github.com" class="unknown">API Status</a></div>
</div><!-- /sidebar-shell -->
</div><!-- #wrapper -->
<div id="footer" >
<div class="lower_footer">
<ul class="footer-cell">
<li><a href="http://help.github.com/terms-of-service/">Terms</a></li>
<li><a href="http://help.github.com/privacy-policy/">Privacy</a></li>
<li><a href="http://help.github.com/security/">Security</a></li>
<li><a href="https://github.com/contact">Contact</a></li>
</ul>
<span class="footer-cell">
<a href="https://github.com" class="mega-octicon octicon-mark-github"></a>
</span>
<ul class="footer-cell">
<li><a href="https://status.github.com/">Status</a></li>
<li><a href="http://training.github.com/">Training</a></li>
<li><a href="http://shop.github.com/">Shop</a></li>
<li><a href="https://github.com/blog">Blog</a></li>
<li><a href="https://github.com/about">About</a></li>
</ul>
</div>
<div class="wrapper">
<p>Design © <span class="js-year">2014</span> GitHub, Inc. All rights reserved. Except where otherwise noted, content on this site is licensed under a <a href="http://creativecommons.org/licenses/by/3.0/us/">Creative Commons CC-BY license</a>.</p>
</div>
</div><!-- /#footer -->
<script type="text/javascript">
var _gauges = _gauges || [];
(function() {
var t = document.createElement('script');
t.type = 'text/javascript';
t.async = true;
t.id = 'gauges-tracker';
t.setAttribute('data-site-id', '4f2038e0cb25bc1b55000003');
t.src = '//secure.gaug.es/track.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(t, s);
})();
</script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-3769691-27']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<script src="/shared/js/retina.js" type="text/javascript"></script>
</body>
</html>