{{ message }}
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
2333 lines (1788 loc) · 94.8 KB
/
Copy pathindex.html
File metadata and controls
2333 lines (1788 loc) · 94.8 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
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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="blog">
<div id="header-wrapper">
<div id="header">
<div>
<a class="logo" href="/">GitHub:Developer</a>
<ul class="nav">
<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 id="wrapper">
<div class="content">
<div class="change" id="/changes/2014-01-29-audit-org-members-for-2fa/">
<h2 class="title">
<a href="/changes/2014-01-29-audit-org-members-for-2fa/">Audit organization members for two-factor authentication</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
January 29, 2014
</li>
<li 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">
<a href="https://github.com/pengwynn">pengwynn</a>
</li>
</ul>
</div>
<p>We’ve added a <a href="/v3/orgs/members/#audit-two-factor-auth">new filter</a> for listing members of an organization without
<a href="https://github.com/blog/1614-two-factor-authentication">two-factor authentication</a> enabled:</p>
<pre class="terminal">
$ curl -H "Authorization: token [yours]" \
https://api.github.com/orgs/octokit/members\?filter\=2fa_disabled
</pre>
<p>The new filter is available for owners of organizations with private
repositories. Happy auditing and <a href="https://github.com/contact?form%5Bsubject%5D=API+2FA+filter">send us your feedback or questions</a>.</p>
</div>
<div class="change" id="/changes/2014-01-09-preview-the-new-deployments-api/">
<h2 class="title">
<a href="/changes/2014-01-09-preview-the-new-deployments-api/">Preview the New Deployments API</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
January 9, 2014
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/a86224d72ce21cd9f5bee6784d4b06c7?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/atmos">atmos</a>
</li>
</ul>
</div>
<p>Today we’re excited to announce a <a href="/v3/repos/deployments/">Deployments API</a>. We ship a lot of
software at GitHub: web, mobile, and native. For the last few years, we’ve been
driving our deployments from our <a href="https://speakerdeck.com/jnewland/chatops">ChatOps tooling</a> and we’ve learned a
lot. The Deployments API is a generalization of the approach that we’ve been
taking, and we’re really excited to see what our users and integrations start
building around it.</p>
<p>Deployments are a new model in the GitHub ecosystem. We don’t have any UI
components currently, and deployments are intended to be used exclusively by
tooling. If you’re familiar with the Status API, you know that it allows
various tools to report on the status of a commit (e.g., the progress of an
attempt to perform a build at a particular commit). The Status API doesn’t
perform the build; it just reports the results. Much like the Status API, we
won’t be doing actual deployments for you. Instead, the API provides a way for
you to track the status of your deployments. We’re hoping to provide
consistency across the various type of release processes, regardless of the
underlying steps involved with getting your code built or shipped to your
servers.</p>
<h2 id="highlights">Highlights</h2>
<h3 id="automatic-merging">Automatic Merging</h3>
<p>The system can auto-merge the default branch for the repository if the
requested deployment ref is behind the default branch. On active projects it’s
easy to fall behind, so let automation watch your back.</p>
<h3 id="commit-status-integration">Commit Status Integration</h3>
<p>By default, the system rejects deployment requests for repositories that have
commit statuses but don’t have a green build for the deployment ref. This can
be bypassed, but is useful in cases where continuous integration is being used.</p>
<h3 id="force-deployments">Force Deployments</h3>
<p>Sometimes the world crashes down on you, and you need to just get the code out
the door. Forced deployments bypass any commit status checks or ahead/behind
checks in the repository.</p>
<h3 id="deployment-statuses">Deployment Statuses</h3>
<p>Different deployment systems can update the status of a deployment to be
<code>pending</code>, <code>success</code>, <code>failure</code>, or <code>error</code>. There’s also a field for linking
to deployment output.</p>
<h3 id="events">Events</h3>
<p>Both Deployments and Deployment Statuses trigger events on GitHub. 3rd party
integrations can listen for these events via <a href="/v3/repos/hooks/">webhooks</a> and choose
whether or not to actually deploy the repository that the event was created for.</p>
<h2 id="preview-period">Preview Period</h2>
<p>We’re making this new API available today for developers to
<a href="/v3/repos/deployments/#preview-mode" data-proofer-ignore>preview</a>. We think developers and existing integrations are
going to love it, but we want to <a href="https://github.com/contact?form%5Bsubject%5D=Deployments+API">get your feedback</a> before we declare
the Deployments API “final” and “unchangeable.” We expect the preview period to
last for roughly 60-90 days.</p>
<p>As we discover opportunities to improve the API during the preview period, we
may ship changes that break clients using the preview version of the API. We
want to iterate quickly. To do so, we will announce any changes here (on the
developer blog), but we will not provide any advance notice.</p>
<p>At the end of preview period, the Deployments API will become an official
component of GitHub API v3. At that point, the new Deployments API will be
stable and suitable for production use.</p>
<p>We hope you’ll take it for a spin and <a href="https://github.com/contact?form%5Bsubject%5D=Deployments+API">send us your feedback</a>.</p>
<p><img src="http://shipitsquirrel.github.io/images/ship%20it%20squirrel.png" alt=""></p>
</div>
<div class="change" id="/changes/2014-01-07-upcoming-change-to-default-media-type/">
<h2 class="title">
<a href="/changes/2014-01-07-upcoming-change-to-default-media-type/">Upcoming Change to Default Media Type</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
January 7, 2014
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/592e1e6f041f9a4ec51846fd82013aea?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/jasonrudolph">jasonrudolph</a>
</li>
</ul>
</div>
<p>On April 15, 2014<a href="#cutover-test">*</a>, the GitHub API will start serving the v3 media type by default. The information below will help you determine whether your applications will be affected by this change. For affected applications, you’ll find tips below to help you smoothly navigate this change.</p>
<h2 id="whats-changing">What’s changing?</h2>
<h3 id="a-new-default-version">A new default version</h3>
<p>There are <a href="/v3/versions">two versions</a> of the GitHub API: <strong>beta</strong> and <strong>v3</strong>. Today, requests receive the beta version by default. On April 15<a href="#cutover-test">*</a>, requests will begin receiving the v3 version by default.</p>
<p>For the most part, beta and v3 are remarkably similar. There are <a href="/v3/versions/#differences-from-beta-version">just a few differences</a> to keep in mind.</p>
<h3 id="a-new-default-media-type">A new default media type</h3>
<p>The version is one part of the <a href="/v3/media">media type</a>. By default, the API provides the beta media type:</p>
<pre><code>application/vnd.github.beta+json
</code></pre>
<p>On April 15<a href="#cutover-test">*</a>, requests will begin responding with the v3 media type by default:</p>
<pre><code>application/vnd.github.v3+json
</code></pre>
<h2 id="who-is-affected">Who is affected?</h2>
<p>Since 2012, we have encouraged developers to explicitly <a href="/v3/media/#beta-v3-and-the-future">request a specific media type via the <code>Accept</code> header</a>. If you are requesting either beta or v3 via the <code>Accept</code> header, then you are <em>not</em> affected by this change. The API will continue to respond with the requested media type.</p>
<p>If you are not requesting beta or v3 via the <code>Accept</code> header, then the API is currently responding with the beta media type. On April 15<a href="#cutover-test">*</a>, the API will begin responding with the v3 media type. If your application relies on <a href="/v3/versions/#differences-from-beta-version">functionality that differs between beta and v3</a>, then you are affected by this change. You will need to take steps to prepare for the change.</p>
<h2 id="what-should-you-do">What should you do?</h2>
<p>If you are affected by this change, we recommend that you:</p>
<ol>
<li>Update your applications to depend on the v3 functionality instead of the beta functionality. (If you use one of the popular <a href="/libraries/">client libraries</a>, there’s a good chance that they’ve already done the work for you. In that case, you can just update to the latest version of that library.)</li>
<li>Request the v3 media type via the <code>Accept</code> header.</li>
</ol>
<p>If you cannot update your application to depend on the v3 functionality by April 15<a href="#cutover-test">*</a>, you can just request the beta media type via the <code>Accept</code> header. Doing so will insulate you from this change.</p>
<h2 id="cutover-test">Cutover test on March 12, 2014</h2>
<p>To help you understand the impact of this change before it becomes permanent, we will temporarily implement this change for a single day on March 12. From approximately 12:01am UTC to 11:59pm UTC on March 12, the API will respond with the v3 media type by default.</p>
<p>Follow <a href="https://twitter.com/GitHubAPI">@GitHubAPI</a> to receive updates before and after the test.</p>
<h2 id="stay-informed">Stay informed</h2>
<p>Depending on the results of the cutover test, we may schedule additional tests before the final cutover on April 15. If so, we’ll to announce them in advance. Be sure to stay tuned to the <a href="/changes">blog</a> or follow <a href="https://twitter.com/GitHubAPI">@GitHubAPI</a> for updates.</p>
<p>If you have any questions, please <a href="https://github.com/contact?form%5Bsubject%5D=Upcoming+change+to+default+API+media+type">get in touch</a>. We’ll be happy to help.</p>
</div>
<div class="change" id="/changes/2013-12-13-paginating-org-members/">
<h2 class="title">
<a href="/changes/2013-12-13-paginating-org-members/">Paginated results for organization members</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
December 13, 2013
</li>
<li 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">
<a href="https://github.com/pengwynn">pengwynn</a>
</li>
</ul>
</div>
<p>The <a href="http://developer.github.com/v3/orgs/members/#members-list">organization members</a> and <a href="http://developer.github.com/v3/orgs/members/#public-members-list">organization public members</a> methods will soon return paginated results by default. Beginning
today, these methods will paginate if you include <code>page</code> or <code>per_page</code> query
parameters. Starting January 15th, 2014, these methods will <em>always</em> return paginated
results.</p>
<p>As always, be sure and follow those <a href="http://developer.github.com/v3/#pagination">Link headers</a> to get
subsequent results. If you have any questions or run into trouble, feel free to
<a href="https://github.com/contact?form%5Bsubject%5D=API+v3:+Paginating+org+members">get in touch</a>.</p>
<p>Happy paginating.</p>
</div>
<div class="change" id="/changes/2013-11-04-releases-api-is-official/">
<h2 class="title">
<a href="/changes/2013-11-04-releases-api-is-official/">Releases API is Official</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
November 4, 2013
</li>
<li 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">
<a href="https://github.com/technoweenie">technoweenie</a>
</li>
</ul>
</div>
<p>Hot on the heels of the <a href="http://developer.github.com/changes/2013-10-29-search-api-becomes-an-official-part-of-github-api-v3/">Search API</a>, the <a href="/v3/repos/releases/">Releases API</a>
is now officially part of GitHub API v3. We now consider it stable for
production use. </p>
<h3 id="preview-media-type-no-longer-needed">Preview Media Type No Longer Needed</h3>
<p>If you used the Releases API during the preview period, you needed to provide a custom media type in the <code>Accept</code> header:</p>
<pre><code>application/vnd.github.manifold-preview+json
</code></pre>
<p>Now that the preview period has ended, you no longer need to pass this custom media type.</p>
<p>Instead, we <a href="/v3/media">recommend</a> that you specify <code>v3</code> as the version in the <code>Accept</code> header:</p>
<pre><code>application/vnd.github.v3+json
</code></pre>
<h3 id="onward">Onward!</h3>
<p>Thanks again to everyone that tried out the Releases API during the preview period.
We got some great feedback, and we are already discussing additions to the API.</p>
<p>We can’t wait to see what you ship!</p>
</div>
<div class="change" id="/changes/2013-10-29-search-api-becomes-an-official-part-of-github-api-v3/">
<h2 class="title">
<a href="/changes/2013-10-29-search-api-becomes-an-official-part-of-github-api-v3/">Search API Becomes an Official Part of API v3</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
October 29, 2013
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/592e1e6f041f9a4ec51846fd82013aea?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/jasonrudolph">jasonrudolph</a>
</li>
</ul>
</div>
<p>We’re excited to announce that the <a href="/v3/search">new Search API</a> has graduated from <a href="/changes/2013-07-19-preview-the-new-search-api/#preview-period">preview mode</a>.
As of today, the Search API is an official part of <a href="/v3">GitHub API v3</a>.
As such, the Search API is now stable and suitable for production use.</p>
<h3 id="preview-media-type-no-longer-needed">Preview Media Type No Longer Needed</h3>
<p>If you used the Search API during the preview period, you needed to provide a custom media type in the <code>Accept</code> header:</p>
<pre><code>application/vnd.github.preview+json
</code></pre>
<p>Now that the preview period has ended, you no longer need to pass this custom media type.</p>
<p>Instead, we <a href="/v3/media">recommend</a> that you specify <code>v3</code> as the version in the <code>Accept</code> header:</p>
<pre><code>application/vnd.github.v3+json
</code></pre>
<h3 id="onward">Onward!</h3>
<p>Thanks again to everyone that tried out the Search API during the preview period.</p>
<p>We can’t wait to see what you build!</p>
</div>
<div class="change" id="/changes/2013-10-18-new-code-search-requirements/">
<h2 class="title">
<a href="/changes/2013-10-18-new-code-search-requirements/">New Validation Rule for Beta Code Search API</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
October 18, 2013
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/592e1e6f041f9a4ec51846fd82013aea?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/jasonrudolph">jasonrudolph</a>
</li>
</ul>
</div>
<p>As we <a href="/changes/2013-09-28-an-update-on-the-new-search-api/">prepare to end the preview period</a> for the new search API,
we’re making sure that it’s ready to handle the traffic from all the apps you’ll build on top of it.</p>
<h2 id="new-validation-rule">New Validation Rule</h2>
<p>In order to support the expected volume of requests, we’re applying a new validation rule to the <a href="/v3/search/#search-code">Code Search API</a>.
Starting today, you will need to scope your code queries to a specific set of users, organizations, or repositories.</p>
<p>As usual, you specify the query via the <code>q</code> parameter.
The value must include <a href="https://help.github.com/articles/searching-code#users-organizations-and-repositories">at least one user, organization, or repository</a>.</p>
<p>For example, with this query, we’re searching for code from <a href="https://github.com/twitter">@twitter</a> or <a href="https://github.com/facebook">@facebook</a> that uses an MIT License:</p>
<pre><code>MIT License user:twitter user:facebook
</code></pre>
<p>And here, we’re looking for uses of the underscore library in <a href="https://github.com/mozilla/BrowserQuest">@mozilla’s BrowserQuest</a> repository:</p>
<pre><code>underscore language:js repo:mozilla/BrowserQuest
</code></pre>
<p>To perform these queries via the API, we would use the following URLs (respectively):</p>
<pre><code>https://api.github.com/search/code?q=MIT+License+user%3Atwitter+user%3Afacebook
https://api.github.com/search/code?q=underscore+language%3Ajs+repo%3Amozilla%2FBrowserQuest
</code></pre>
<p>All the various <a href="https://help.github.com/articles/searching-code">code search qualifiers</a> are still available to you.
A <a href="https://help.github.com/articles/searching-code#users-organizations-and-repositories">user, organization, or repository qualifier</a> is now required.
The other search qualifiers are still optional.</p>
<h2 id="other-search-types-not-affected">Other Search Types Not Affected</h2>
<p>This new validation only applies to the <a href="/v3/search/#search-code">Code Search API</a>.
It does not apply to the Search API for <a href="/v3/search/#search-issues">issues</a>, <a href="/v3/search/#search-users">users</a>, or <a href="/v3/search/#search-repositories">repositories</a>.</p>
<p>This validation does not affect searches performed on <a href="https://github.com/search">github.com/search</a>.</p>
<p>By ensuring that code queries are more targeted in nature, the API will be ready to meet the expected demand from all your apps.
As we continue to tune the Search API, we hope to relax this validation in the future.
There’s no ETA, but we’d like to relax it as soon as it’s feasible.</p>
<p>As always, if you have any questions or feedback, please <a href="https://github.com/contact?form%5Bsubject%5D=New+Validation+Rule+for+Code+Search+API">get in touch</a>.</p>
</div>
<div class="change" id="/changes/2013-10-08-list-all-user-teams/">
<h2 class="title">
<a href="/changes/2013-10-08-list-all-user-teams/">List all teams for the authenticated user</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
October 8, 2013
</li>
<li 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">
<a href="https://github.com/pengwynn">pengwynn</a>
</li>
</ul>
</div>
<p>We just added a <a href="/v3/orgs/teams/#list-user-teams">new API method</a> to list all
the teams for the authenticated user across all organizations:</p>
<pre class="terminal">
$ curl -H "Authorization: token [yours]" https://api.github.com/user/teams
[
{
"name": "Testing",
"id": 396018,
"slug": "testing",
"permission": "pull",
"url": "https://api.github.com/teams/396018",
"members_url": "https://api.github.com/teams/396018/members{/member}",
"repositories_url": "https://api.github.com/teams/396018/repos",
"members_count": 1,
"repos_count": 0,
"organization": {
"login": "dotfiles",
"id": 1593590,
"url": "https://api.github.com/orgs/dotfiles",
"repos_url": "https://api.github.com/orgs/dotfiles/repos",
"events_url": "https://api.github.com/orgs/dotfiles/events",
"members_url": "https://api.github.com/orgs/dotfiles/members{/member}",
"public_members_url": "https://api.github.com/orgs/dotfiles/public_members{/member}",
"avatar_url": "https://0.gravatar.com/avatar/67d30facf213f62853c119fc2a05e246?d=https%3A%2F%2Fidenticons.github.com%2Fc90a68e6ab739e81c642f0e93f88c722.png"
}
},
...
]
</pre>
<p>As always, if you have any questions or feedback, please <a href="https://github.com/contact?form%5Bsubject%5D=API+-+Listing+Teams+for+User">drop us a line</a>.</p>
</div>
<div class="change" id="/changes/2013-10-04-oauth-changes-coming/">
<h2 class="title">
<a href="/changes/2013-10-04-oauth-changes-coming/">OAuth changes coming</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
October 4, 2013
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/2f4861b27dc35663ed271d39f5358261?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/tclem">tclem</a>
</li>
</ul>
</div>
<p>Starting today, we are returning granted scopes as part of the
<a href="/v3/oauth/#github-redirects-back-to-your-site">access_token response</a>.
For example, if you are making a POST with the <code>application/json</code>
mime-type you’ll see an additional field for the granted scopes.</p>
<pre><code class="language-javascript"><span class="p">{</span>
<span class="s2">"access_token"</span><span class="o">:</span><span class="s2">"e72e16c7e42f292c6912e7710c838347ae178b4a"</span><span class="p">,</span>
<span class="s2">"scope"</span><span class="o">:</span><span class="s2">"repo,gist"</span><span class="p">,</span>
<span class="s2">"token_type"</span><span class="o">:</span><span class="s2">"bearer"</span>
<span class="p">}</span></code></pre>
<p>Right now, these scopes will be identical to what you requested, but we
are moving towards a feature set that will allow GitHub users to edit
their scopes, effectively granting your application less access than you
originally requested. You should be aware of this possibility and adjust
your application behavior accordingly.</p>
<p>Some things to watch out for and keep in mind:</p>
<ul>
<li>
<p>Most third party applications using GitHub OAuth to identify users have
the best success in adoption by starting out with a request for the
minimum access that the application can possibly get away with.
Something like no scopes or just <code>user:email</code> is very sane.</p>
</li>
<li>
<p>It is important to handle the error cases where a user chooses to
grant you less access than you originally requested. Now that we are
surfacing the granted scopes on the access_token response, applications
can warn or otherwise communicate with their users that they will see
reduced functionality or be unable to perform some actions.</p>
</li>
<li>
<p>Applications can always send users back through the flow again to get
additional permission, but don’t forget that users can always say no.</p>
</li>
</ul>
</div>
<div class="change" id="/changes/2013-09-28-an-update-on-the-new-search-api/">
<h2 class="title">
<a href="/changes/2013-09-28-an-update-on-the-new-search-api/">An Update on the New Search API</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
September 28, 2013
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/592e1e6f041f9a4ec51846fd82013aea?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/jasonrudolph">jasonrudolph</a>
</li>
</ul>
</div>
<p>We owe a big “Thank You!” to everyone that has taken the time to try out the <a href="/changes/2013-07-19-preview-the-new-search-api">new Search API</a>.
We <code>:heart:</code> every one of you.
Just as we hoped,
the <a href="/changes/2013-07-19-preview-the-new-search-api/#preview-period">preview period</a> has allowed us to see how you want to use the new API,
and it has given us a chance to improve the API before finalizing it.</p>
<p>In order to incorporate everything that we’ve learned,
we’re going to keep the Search API in <a href="/changes/2013-07-19-preview-the-new-search-api/#preview-period">preview mode</a> for a little while longer.
We have a few bugs to squash and a couple performance kinks to iron out.
We’re hard at work on those improvements now,
and we expect to have more news in the coming weeks.</p>
<p>In the mean time, <a href="https://github.com/contact?form%5Bsubject%5D=New+Search+API">keep the suggestions coming</a>!</p>
</div>
<div class="change" id="/changes/2013-09-25-releases-api/">
<h2 class="title">
<a href="/changes/2013-09-25-releases-api/">Releases API</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
September 25, 2013
</li>
<li 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">
<a href="https://github.com/technoweenie">technoweenie</a>
</li>
</ul>
</div>
<p>This summer we made it easier to <a href="https://github.com/blog/1547-release-your-software">release your software</a>. Today, you can fully automate those releases via the
<a href="http://developer.github.com/v3/repos/releases/">Releases API Preview</a>.</p>
<p>This API is a little different due to the binary assets. We use the <code>Accept</code> header for content negotiation when requesting
a release asset. Pass a standard API media type to get the API representation:</p>
<pre class="terminal">
$ curl -i -H "Authorization: token TOKEN" \
-H "Accept: application/vnd.github.manifold-preview" \
"https://uploads.github.com/repos/hubot/singularity/releases/assets/123"
HTTP/1.1 200 OK
{
"id": 123,
...
}
</pre>
<p>Pass “application/octet-stream” to download the binary content.</p>
<pre class="terminal">
$ curl -i -H "Authorization: token TOKEN" \
-H "Accept: application/octet-stream" \
"https://uploads.github.com/repos/hubot/singularity/releases/assets/123"
HTTP/1.1 302 Found
</pre>
<p>Uploads are handled by a single request to a companion “uploads.github.com” service.</p>
<pre class="terminal">
$ curl -H "Authorization: token TOKEN" \
-H "Accept: application/vnd.github.manifold-preview" \
-H "Content-Type: application/zip" \
--data-binary @build/mac/package.zip \
"https://uploads.github.com/repos/hubot/singularity/releases/123/assets?name=1.0.0-mac.zip"
</pre>
<h2 id="preview-mode">Preview mode</h2>
<p>The new API is available as a <a href="http://developer.github.com/v3/repos/releases/#preview-mode">preview</a>. This gives developers a chance to <a href="https://github.com/contact?form%5Bsubject%5D=New+Releases+API">provide feedback</a> on the direction of
the API before we freeze changes. We expect to lift the preview status in 30 days.</p>
<p>As with <a href="http://developer.github.com/changes/2013-07-19-preview-the-new-search-api/">the Search API</a>, we’ll take this opportunity to iterate quickly. Breaking changes will be announced
on this developer blog without any advance warning. Once the preview period is over, we’ll consider the Releases API unchangeable.
At that point, it will be stable and suitable for production use.</p>
<p>The preview media type is “application/vnd.github.manifold-preview”. <a href="http://en.wikipedia.org/wiki/Eden_Fesi">Manifold</a> is
a member of the Avengers, with the ability to teleport through time and space. He’s the one in the middle holding the spear.</p>
<p><img src="https://f.cloud.github.com/assets/21/1210628/ae8556fa-25fc-11e3-986d-0ab522271d43.png" alt="Manifold teleporting the Avengers to a terraformed Mars surface"></p>
</div>
<div class="change" id="/changes/2013-09-03-two-factor-authentication/">
<h2 class="title">
<a href="/changes/2013-09-03-two-factor-authentication/">Two-Factor Authentication and the API</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
September 3, 2013
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/8caa0afdae1a934c30a1998472c63134?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/mastahyeti">mastahyeti</a>
</li>
</ul>
</div>
<p>As <a href="https://github.com/blog/1614-two-factor-authentication">announced earlier today</a>, GitHub.com now supports two-factor
authentication (2FA) for increased security. For users with this feature
enabled, GitHub.com will prompt for a 2FA code in addition to a username and
password during authentication. We’ve also rolled out some improvements to the
API to ensure that 2FA requirements in the API are consistent with GitHub.com.</p>
<h2 id="authenticating-with-the-api">Authenticating with the API</h2>
<p>For users without 2FA enabled, and for applications using the <a href="/v3/oauth/#web-application-flow">OAuth web
flow</a> for authentication, everything is
business as usual. You’ll continue to authenticate with the API just as you
always have. (That was easy.)</p>
<p>If you enable 2FA <em>and</em> use Basic Authentication to access the API, we’re
providing multiple options to make the flow simple and easy.</p>
<h2 id="basic-authentication-and-2fa">Basic Authentication and 2FA</h2>
<h3 id="personal-access-tokens">Personal Access Tokens</h3>
<p>Personal access tokens provide the simplest option for using 2FA with Basic
Authentication. You can create these tokens via the <a href="https://github.com/settings/applications">application settings page
on GitHub.com</a>, and you can revoke
them at any time. For more information about authenticating to the API with
personal access tokens, be sure to check out our <a href="https://help.github.com/articles/creating-an-access-token-for-command-line-use">help article on the
topic</a>.</p>
<h3 id="tightly-integrated-2fa">Tightly-integrated 2FA</h3>
<p>For developers wishing to integrate GitHub 2FA directly into their application,
the API’s Basic Authentication now supports the <a href="/v3/auth/#working-with-two-factor-authentication">ability to send the user’s 2FA
code</a>, in addition to the username and password.</p>
<h2 id="were-here-to-help">We’re here to help</h2>
<p>We think GitHub users are going to love the additional security provided by
two-factor authentication. As always, if you have any questions or feedback,
<a href="https://github.com/contact?form%5Bsubject%5D=2FA+and+the+API">let us know</a>. We’re here to help!</p>
</div>
<div class="change" id="/changes/2013-08-20-search-api-improvements/">
<h2 class="title">
<a href="/changes/2013-08-20-search-api-improvements/">Improvements to the Search API</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
August 20, 2013
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/592e1e6f041f9a4ec51846fd82013aea?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/jasonrudolph">jasonrudolph</a>
</li>
</ul>
</div>
<p>Today we’re shipping two improvements to the <a href="/changes/2013-07-19-preview-the-new-search-api/">new Search API</a>.</p>
<h2 id="more-text-match-metadata">More Text Match Metadata</h2>
<p>When searching for code, the API previously provided <a href="/v3/search/#text-match-metadata">text match metadata</a> (i.e., “highlights”) for file content.
Now, you can also <a href="/v3/search/#highlighting-code-search-results">get this metadata</a> for matches that occur within the file path.</p>
<p>For example, when <a href="https://github.com/search?q=%40octokit%2Foctokit.rb+in%3Apath+client&type=Code">searching for files that have “client” in their path</a>, the results include this match for <code>lib/octokit/client/commits.rb</code>:</p>
<pre class="json">
{
"name": "commits.rb",
"path": "lib/octokit/client/commits.rb",
"text_matches": [
{
"object_url": "https://api.github.com/repositories/417862/contents/lib/octokit/client/commits.rb?ref=8d487ab06ccef463aa9f5412a56f1a2f1fa4dc88",
"object_type": "FileContent",
"property": "path",
"fragment": "lib/octokit/client/commits.rb",
"matches": [
{
"text": "client",
"indices": [ 12, 18 ]
}
]
}
]
// ...
}
</pre>
<h2 id="better-text-match-metadata">Better Text Match Metadata</h2>
<p>Before today, the API applied HTML entity encoding to all <code>fragment</code> data.
For example, imagine your search returns an issue like <a href="https://github.com/rails/rails/issues/11889">rails/rails#11889</a>:</p>
<p><img src="https://f.cloud.github.com/assets/2988/994632/a84f2888-09af-11e3-9417-4bd92f1f1ed6.png" alt="Example Issue Title"></p>
<p>The response would include a <code>text_matches</code> array with the following object:</p>
<pre class="json">
{
"fragment": "undefined method `except' for #&lt;Array:XXX&gt;",
// ...
}
</pre>
<p>Inside the <code>fragment</code> value, we see HTML-encoded entities (e.g., <code>&lt;</code>).
Since we’re returning JSON (not HTML), API clients might not expect any HTML-encoded text.
As of today, the API returns these fragments <em>without</em> this extraneous encoding.</p>
<pre class="json">
{
"fragment": "undefined method `except' for #<Array:XXX>",
// ...
}
</pre>
<h2 id="preview-period">Preview Period</h2>
<p>We’re about halfway through the <a href="/changes/2013-07-19-preview-the-new-search-api/#preview-period">preview period</a> for the new Search API.
We appreciate everyone that has provided feedback so far. Please <a href="https://github.com/contact?form%5Bsubject%5D=New+Search+API">keep it coming</a>!</p>
</div>
<div class="change" id="/changes/2013-07-19-preview-the-new-search-api/">
<h2 class="title">
<a href="/changes/2013-07-19-preview-the-new-search-api/">Preview the New Search API</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
July 19, 2013
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/592e1e6f041f9a4ec51846fd82013aea?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/jasonrudolph">jasonrudolph</a>
</li>
</ul>
</div>
<p>Today we’re excited to announce a <a href="/v3/search/">brand new Search API</a>. Whether you’re
searching for <a href="/v3/search/#search-code">code</a>, <a href="/v3/search/#search-repositories">repositories</a>,
<a href="/v3/search/#search-issues">issues</a>, or <a href="/v3/search/#search-users">users</a>, all the query abilities of
github.com are now available via the API as well.</p>
<p>Maybe you want to find <a href="/v3/search/#repository-search-example">popular Tetris implementations written in Assembly</a>.
We’ve got you covered.
Or perhaps you’re looking for <a href="/v3/search/#code-search-example">new gems that are using Octokit.rb</a>.
No problem.
The possibilities are endless.</p>
<h2 id="highlights">Highlights</h2>
<p>On github.com, we enjoy the context provided by code snippets and highlights in
search results.</p>
<p><a href="https://github.com/search?q=faraday+builder+repo%3Aoctokit%2Foctokit.rb&type=Code"><img src="https://f.cloud.github.com/assets/865/819651/959a4826-efb5-11e2-8af8-46c4a3857cdf.png" alt="code-snippet-highlighting"></a></p>
<p>We want API consumers to have access to that information as well. So, API
requests can opt to receive those
<a href="/v3/search#text-match-metadata">text fragments in the response</a>. Each fragment is accompanied by
numeric offsets identifying the exact location of each matching search term.</p>
<h2 id="preview-period">Preview period</h2>
<p>We’re making this new API available today for developers to
<a href="/v3/search/#preview-mode">preview</a>. We think developers are going to love it, but we want
to get your feedback before we declare the Search API “final” and
“unchangeable.” We expect the preview period to last for roughly 60 days.</p>
<p>As we discover opportunities to improve this new API during the preview period,
we may ship changes that break clients using the preview version of the API. We
want to iterate quickly. To do so, we will announce any changes here (on the
developer blog), but we will not provide any advance notice.</p>
<p>At the end of preview period, the Search API will become an official component
of GitHub API v3. At that point, the new Search API will be stable and suitable
for production use.</p>
<h2 id="what-about-the-old-search-api">What about the old search API?</h2>
<p>The <a href="/v3/search/legacy/">legacy search API</a> is still available. Many existing clients
depend on it, and it is not changing in any way. While the new API offers much
more functionality, the legacy search endpoints remain an official part of
GitHub API v3.</p>
<h2 id="take-it-for-a-spin">Take it for a spin</h2>
<p>We hope you’ll kick the tires and <a href="https://github.com/contact?form%5Bsubject%5D=New+Search+API">send us your feedback</a>. Happy
<del>searching</del> finding!</p>
</div>
<div class="change" id="/changes/2013-07-02-rate-limit-reset/">
<h2 class="title">
<a href="/changes/2013-07-02-rate-limit-reset/">When Does My Rate Limit Reset?</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
July 2, 2013
</li>
<li class="who_when">
<img height="16" width="16" src="https://secure.gravatar.com/avatar/592e1e6f041f9a4ec51846fd82013aea?s=20&d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png">
<a href="https://github.com/jasonrudolph">jasonrudolph</a>
</li>
</ul>
</div>
<p>Have you ever wondered when your <a href="/v3/#rate-limiting">rate limit</a> will reset back to its maximum value?
That information is now available in the new <code>X-RateLimit-Reset</code> response header.</p>
<pre class="terminal">
$ curl -I https://api.github.com/orgs/octokit
HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1372700873
...
</pre>
<p>The <code>X-RateLimit-Reset</code> header provides a <a href="http://en.wikipedia.org/wiki/Unix_time">Unix UTC timestamp</a>, letting you know the exact time that your fresh new rate limit kicks in.</p>
<p>The reset timestamp is also available as part of the <code>/rate_limit</code> resource.</p>
<pre class="terminal">
$ curl https://api.github.com/rate_limit
{
"rate": {
"limit": 60,
"remaining": 42,
"reset": 1372700873
}
}
</pre>
<p>For more information on rate limits, be sure to check out the <a href="/v3/#rate-limiting">docs</a>.</p>
<p>If you have any questions or feedback, please <a href="https://github.com/contact?form%5Bsubject%5D=X-RateLimit-Reset">drop us a line</a>.</p>
</div>
<div class="change" id="/changes/2013-07-01-feeds-api/">
<h2 class="title">
<a href="/changes/2013-07-01-feeds-api/">Feeds API</a>
</h2>
<div class="meta">
<ul>
<li class="published">
<span class="octicon octicon-calendar"></span>
July 1, 2013
</li>
<li 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">
<a href="https://github.com/pengwynn">pengwynn</a>
</li>
</ul>
</div>
<p>Today we’re releasing a new <a href="/v3/activity/feeds/">Feeds API</a>, an easy way to list all the Atom
resources available to the authenticated user.</p>
<pre class="terminal">
curl -u defunkt https://api.github.com/feeds
{
"timeline_url": "https://github.com/timeline",
"user_url": "https://github.com/{user}",
"current_user_public_url": "https://github.com/defunkt",
"current_user_url": "https://github.com/defunkt.private?token=abc123",
"current_user_actor_url": "https://github.com/defunkt.private.actor?token=abc123",
"current_user_organization_url": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123",
"_links": {
"timeline": {
"href": "https://github.com/timeline",
"type": "application/atom+xml"
},
"user": {
"href": "https://github.com/{user}",
"type": "application/atom+xml"
},
"current_user_public": {
"href": "https://github.com/defunkt",
"type": "application/atom+xml"
},
"current_user": {
"href": "https://github.com/defunkt.private?token=abc123",
"type": "application/atom+xml"
},
"current_user_actor": {
"href": "https://github.com/defunkt.private.actor?token=abc123",
"type": "application/atom+xml"
},
"current_user_organization": {
"href": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123",
"type": "application/atom+xml"
}
}
}
</pre>
You can’t perform that action at this time.