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
468 lines (405 loc) · 21 KB
/
Copy pathindex.html
File metadata and controls
468 lines (405 loc) · 21 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
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
<!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>GitHub API Changes</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="/"><img src="/images/logo_developer.png" width="255" height="45" alt="GitHub:Developer" /></a>
<ul class="nav">
<li><a href="/v3/">API v3</a></li>
<li><a href="/changes/">Changes</a></li>
<li><a
href="https://github.com/contact">Support</a></li>
<li><a href="/changes.atom">
<img src="/images/feed-icon-28x28.png" width="16" height="16" alt="GitHub API Changes Feed" />
</a></li>
</ul>
</div>
</div><!-- #header -->
</div><!-- #header-wrapper -->
<div id="wrapper">
<div class="content">
<h1 id="api-changes">API Changes</h1>
<div class="change" id="/changes/2012-10-17-org-members-redirection/">
<h2 class="title">
<a href="/changes/2012-10-17-org-members-redirection/">Organization Members Resource Changes</a>
</h2>
<div class="meta">
<div class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/f38112009dc16547051c8ac246cee443?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png"><span class="author vcard fn">
<a href="https://github.com/pezra">pezra</a>
</span>
<span class="published">
October 17, 2012
</span>
</div>
</div>
<p>Requesting the <a href="/v3/orgs/members/index.html#members-list">member list</a> of an
organization of which you are not a member now redirects to the <a href="v3/orgs/members/index.html#public-members-list">public members
list</a>. Similarly, requests to
<a href="/v3/orgs/members/index.html#check-membership">membership check</a> resources of
an organization of which you are not a member are redirected to the equivalent
<a href="/v3/orgs/members/index.html#check-public-membership">public membership check</a>.
One exception to the latter case is that if you are checking about your own
membership the request is not redirected. You are always allowed to know what
organizations you belong to.</p>
<p>The changes where made to clarify the purpose of these various resources. The
<code>/orgs/:org/members</code> resources are intended for use by members of the
organization in question. The <code>/orgs/:org/public_members</code> resources are for
acquiring information about the public membership of organizations. If you are
not a member you are not allowed to see private membership information so you
should be using the public membership resources.</p>
<p>If you have any questions or feedback, please drop us a line at
<a href="mailto:support@github.com?subject=Org%20members%20API">support@github.com</a>.</p>
</div>
<div class="change" id="/changes/2012-10-14-rate-limit-changes/">
<h2 class="title">
<a href="/changes/2012-10-14-rate-limit-changes/">Rate limit changes for unauthenticated requests</a>
</h2>
<div class="meta">
<div class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/7e19cd5486b5d6dc1ef90e671ba52ae0?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png"><span class="author vcard fn">
<a href="https://github.com/pengwynn">pengwynn</a>
</span>
<span class="published">
October 14, 2012
</span>
</div>
</div>
<p>To ensure a high quality of service for all API consumers, we’ve reduced the
default rate limit for unauthenticated requests. To enjoy the default rate
limit of 5,000 requests per hour, you’ll need to
<a href="http://developer.github.com/v3/#authentication">authenticate</a> via Basic Auth
or OAuth. Unauthenticated requests will be limited to 60 per hour unless you
<a href="http://developer.github.com/v3/#unauthenticated-rate-limited-requests">include your OAuth client and
secret</a>.</p>
<p>We’ll soon require all requests to include a valid <a href="http://en.wikipedia.org/wiki/User_agent">User Agent
header</a>. Setting a
unique value for this header helps us identify requests and get in touch with
developers who are abusing the API. Most HTTP libraries, wrapper libraries, and
even cURL provide a valid header for you already and allow you to change it to
something unique to your application.</p>
<p>If you have any questions or feedback, please drop us a line at
<a href="mailto:support@github.com?subject=API%20Rate%20limit">support@github.com</a>.</p>
</div>
<div class="change" id="/changes/2012-9-28-auto-init-for-repositories/">
<h2 class="title">
<a href="/changes/2012-9-28-auto-init-for-repositories/">Initialize a repository when creating</a>
</h2>
<div class="meta">
<div class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/7e19cd5486b5d6dc1ef90e671ba52ae0?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png"><span class="author vcard fn">
<a href="https://github.com/pengwynn">pengwynn</a>
</span>
<span class="published">
September 28, 2012
</span>
</div>
</div>
<p>Today we’ve made it easier to add commits to a repository via the GitHub API.
Until now, you could <a href="/v3/repos/#create">create a repository</a>, but you would
need to initialize it locally via your Git client before adding any commits via
the API.</p>
<p>Now you can optionally init a repository when it’s created by sending <code>true</code>
for the <code>auto_init</code> parameter:</p>
<pre class="terminal">
curl -i -u pengwynn \
-d '{"name": "create-repo-test", "auto_init": true}' \
https://api.github.com/user/repos
</pre>
<p>The resulting repository will have a README stub and an initial commit.</p>
<p><img src="/images/posts/create-repo-init.png" alt="create repo screenshot"></p>
<h3 id="gitignore-templates">.gitignore templates</h3>
<p>Along with this change, you can set up your <code>.gitignore</code> template by passing
the basename of any template in the <a href="https://github.com/github/gitignore">GitHub gitignore templates
project</a>.</p>
<pre class="terminal">
curl -i -u pengwynn \
-d '{"name": "create-repo-test", "auto_init": true, \
"gitignore_template": "Haskell"}' \
https://api.github.com/user/repos
</pre>
<p>As the <a href="/v3/repos/#create">docs point out</a>, the <code>gitignore_template</code> parameter
is ignored if <code>auto_init</code> is not present and <code>true</code>.</p>
<p>If you have any questions or feedback, drop us a line at
<a href="https://github.com/c">https://github.com/contact</a>, <a href="mailto:support@github.com">support@github.com</a>, or
<a href="https://twitter.com/githubapi">@GitHubAPI</a>.</p>
</div>
<div class="change" id="/changes/2012-9-5-watcher-api/">
<h2 class="title">
<a href="/changes/2012-9-5-watcher-api/">Upcoming Changes to Watcher and Star APIs</a>
</h2>
<div class="meta">
<div class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/821395fe70906c8290df7f18ac4ac6cf?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png"><span class="author vcard fn">
<a href="https://github.com/technoweenie">technoweenie</a>
</span>
<span class="published">
September 5, 2012
</span>
</div>
</div>
<p>We recently <a href="https://github.com/blog/1204-notifications-stars">changed the Watcher behavior</a> on GitHub. What
used to be known as “Watching” is now “Starring”. Starring is basically a way
to bookmark interesting repositories. Watching is a way to indicate that you
want to receive email or web notifications on a Repository.</p>
<p>This works well on GitHub.com, but poses a problem for the GitHub API. How do
we change this in a way that developers can gracefully upgrade their
applications? We’re currently looking at rolling out the changes in three
phases over an extended period of time.</p>
<h2 id="current-status">Current Status</h2>
<p>The current <a href="http://developer.github.com/v3/repos/starring/">Repository Starring</a> methods look like this:</p>
<ul>
<li>
<code>/repos/:owner/:repo/watchers</code> - A list of users starring the repository.</li>
<li>
<code>/users/:user/watched</code> - A list of repositories that a user has starred.</li>
<li>
<code>/user/watched</code> - A list of repositories the current user has starred.</li>
</ul>
<h2 id="phase-1-add-watchers-as-subscriptions">Phase 1: Add Watchers as Subscriptions</h2>
<p>This phase exposes Watchers as “Subscriptions”. This is to
keep from clashing with the legacy endpoints. This phase will happen
automatically and will not break your application until Phase 3 starts.</p>
<ul>
<li>
<code>/repos/:owner/:repo/subscribers</code> - A list of users watching the repository.</li>
<li>
<code>/users/:user/subscriptions</code> - A list of repositories that a user is watching.</li>
<li>
<code>/user/subscriptions</code> - A list of repositories the current user is watching.</li>
</ul>
<p>We’ll also add a copy of the legacy Watchers API in the new endpoint:</p>
<ul>
<li>
<code>/repos/:owner/:repo/stargazers</code> - A list of users starring the repository.</li>
<li>
<code>/users/:user/starred</code> - A list of repositories that a user has starred.</li>
<li>
<code>/user/starred</code> - A list of repositories the current user has starred.</li>
</ul>
<p>This is in place <em>now</em> with the current media type for the API:</p>
<pre><code>application/vnd.github.beta+json
</code></pre>
<p>If you care about your application not breaking, make sure all outgoing API
requests pass that value for the “Accept” header. You should do this now. This
can be verified by checking the <code>X-GitHub-Media-Type</code> header on all API
responses.</p>
<pre><code># Accesses a user's starred repositories.
curl https://api.github.com/user/watched \
-H "Accept: application/vnd.github.beta+json"
</code></pre>
<p>This Phase will be broken once Phase 3 starts. Phase 3 removes all support for
the “beta” media type, and makes the “v3” media type the implicit default
for API requests.</p>
<h2 id="phase-2-switch-watchers-api-endpoint">Phase 2: Switch <code>/watchers</code> API Endpoint</h2>
<p>The “watch” endpoints will now be a copy of the “subscription” endpoints. You
will have to use <code>/user/starred</code> to get a user’s starred repositories, not
<code>/user/watched</code>.</p>
<p>This requires a new media type value:</p>
<pre><code>application/vnd.github.v3+json
</code></pre>
<p>This is a breaking change from Phase 1. We will release this change in an
experimental mode first, letting developers gracefully upgrade their
applications by specifying the new media value for the Accept header.</p>
<pre><code># Accesses a user's watched repositories.
curl https://api.github.com/user/watched \
-H "Accept: application/vnd.github.v3+json"
</code></pre>
<h2 id="phase-3-remove-subscribers-api-endpoint">Phase 3: Remove <code>/subscribers</code> API Endpoint.</h2>
<p>This phase involves disabling the subscription endpoints completely. At this
point, you should be using the starring endpoints for starred repositories, and
the watch endpoints for watched repositories. No date has been set yet, but we
expect this to be <em>3-6 months</em> after Phase 2 is in place. This should give
developers enough time for a smooth upgrade path. If they use popular API
wrappers, the work will likely mostly be done for them.</p>
<p>Keep on passing the “v3” media type in your application, until the API has
another breaking change to make. If you can’t make the deadline for Phase 3,
just set the “beta” media type until we shut that down completely. It’s likely
that we will keep the old “beta” media type active for another month, like
the <a href="https://github.com/blog/1090-github-api-moving-on">last time</a> we terminated
old API functionality.</p>
<p>We look forward to assisting you through this transition. Hit us up at
<a href="https://github.com/c">https://github.com/contact</a>, <a href="mailto:support@github.com">support@github.com</a>, or
<a href="https://twitter.com/githubapi">@GitHubAPI</a>.</p>
</div>
</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"> </a><a href="/v3/">Summary</a></h3>
<ul class="js-guides">
<li><a href="/v3/oauth/">OAuth</a></li>
<li><a href="/v3/media/">Media Types</a></li>
<li><a href="/v3/libraries/">Libraries</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed"> </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"> </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"> </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"> </a><a href="/v3/orgs/">Orgs</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"> </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"> </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/downloads/">Downloads</a></li>
<li><a href="/v3/repos/forks/">Forks</a></li>
<li><a href="/v3/repos/keys/">Keys</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/starring/">Starring</a></li>
<li><a href="/v3/repos/statuses/">Statuses</a></li>
<li><a href="/v3/repos/watching/">Watching</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed"> </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/">Keys</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed"> </a><a href="/v3/events/">Events</a></h3>
<ul class="js-guides">
<li><a href="/v3/events/types/">Types</a></li>
</ul>
</li>
<li class="js-topic">
<h3><a href="#" class="js-expand-btn collapsed"> </a><a href="/v3/search/">Search</a></h3>
<ul class="js-guides">
<li><a href="/v3/search/#search-issues">Issues</a></li>
<li><a href="/v3/search/#search-repositories">Repositories</a></li>
<li><a href="/v3/search/#search-users">Users</a></li>
<li><a href="/v3/search/#email-search">Email</a></li>
</ul>
</li>
<li class="js-guides"><h3><a href="/v3/markdown/">Markdown</a></h3></li>
</ul>
</div> <!-- /sidebar-module -->
<div class="sidebar-module">
<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><!-- /sidebar-shell -->
</div><!-- #wrapper -->
<div id="footer" >
<div class="upper_footer">
<div class="footer_inner clearfix">
<!--[if IE]><h4 id="blacktocat_ie">GitHub Links</h4><![endif]-->
<![if !IE]><h4 id="blacktocat">GitHub Links</h4><![endif]>
<ul class="footer_nav">
<h4>GitHub</h4>
<li><a href="https://github.com/about">About</a></li>
<li><a href="https://github.com/blog">Blog</a></li>
<li><a href="https://github.com/features">Features</a></li>
<li><a href="https://github.com/contact">Contact & Support</a></li>
<li><a href="https://github.com/training">Training</a></li>
<li><a href="http://status.github.com/">Site Status</a></li>
</ul>
<ul class="footer_nav">
<h4>Tools</h4>
<li><a href="http://mac.github.com/">GitHub for Mac</a></li>
<li><a href="http://mobile.github.com/">Issues for iPhone</a></li>
<li><a href="https://gist.github.com">Gist: Code Snippets</a></li>
<li><a href="http://enterprise.github.com/">GitHub Enterprise</a></li>
<li><a href="http://jobs.github.com/">Job Board</a></li>
</ul>
<ul class="footer_nav">
<h4>Extras</h4>
<li><a href="http://shop.github.com/">GitHub Shop</a></li>
<li><a href="http://octodex.github.com/">The Octodex</a></li>
</ul>
<ul class="footer_nav">
<h4>Documentation</h4>
<li><a href="http://help.github.com/">GitHub Help</a></li>
<li><a href="http://developer.github.com/">Developer API</a></li>
<li><a href="http://github.github.com/github-flavored-markdown/">GitHub Flavored Markdown</a></li>
<li><a href="http://pages.github.com/">GitHub Pages</a></li>
</ul>
</div><!-- /.site -->
</div><!-- /.upper_footer -->
<div class="lower_footer">
<div class="footer_inner clearfix">
<div id="legal">
<!--[if IE]><a class="home_ie" href="http://github.com">Home</a><![endif]-->
<![if !IE]><a class="home" href="http://github.com">Home</a><![endif]>
<ul id="legal_links">
<li><a href="http://help.github.com/terms-of-service/">Terms of Service</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>
</ul>
<p>© <span id="year">year</span> GitHub Inc. All rights reserved.</p>
</div><!-- /#legal or /#legal_ie-->
</div><!-- /.site -->
</div><!-- /.lower_footer -->
</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>
</body>
</html>