Skip to content

Commit 9f99aa6

Browse files
technoweenietechnoweenie
committed
boom
1 parent b8b7ff1 commit 9f99aa6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+22001
-0
lines changed

‎changes.atom‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<?xml version="1.0" encoding="UTF-8"?><feed xmlns="http://www.w3.org/2005/Atom"><id>http://developer.github.com/</id><title>GitHub API Changes</title>
2+
<updated>2012-09-05T06:00:00Z</updated><link rel="alternate" href="http://developer.github.com/">
3+
<link rel="self" href="http://developer.github.com/changes.atom">
4+
<author><name>technoweenie</name><uri>https://github.com/technoweenie</uri></author><entry><id>tag:developer.github.com,2012-09-05:/changes/2012-9-5-watcher-api/</id><title type="html">Upcoming Changes to Watcher and Star APIs</title>
5+
<published>2012-09-05T06:00:00Z</published><updated>2012-09-05T06:00:00Z</updated><author><name>technoweenie</name><uri>https://github.com/technoweenie</uri></author><link rel="alternate" href="http://developer.github.com/changes/2012-9-5-watcher-api/">
6+
<content type="html">&lt;p&gt;We recently &lt;a href="https://github.com/blog/1204-notifications-stars"&gt;changed the Watcher behavior&lt;/a&gt; on GitHub. What
7+
used to be known as “Watching”, is now “Starring”. Starring is basically
8+
a way to bookmark interesting repositories. Watching is a way to indicate that
9+
you want to receive email or web notifications on a Repository.&lt;/p&gt;
10+
11+
&lt;p&gt;This works well on GitHub.com, but poses a problem for the GitHub API. How do
12+
we change this in a way that developers can gracefully upgrade their
13+
applications? We’re currently looking at rolling out the changes in three
14+
phases over an extended period of time.&lt;/p&gt;
15+
16+
&lt;h2 id="current-status"&gt;Current Status&lt;/h2&gt;
17+
18+
&lt;p&gt;The current &lt;a href="http://developer.github.com/v3/repos/watching/"&gt;Repository Starring&lt;/a&gt; methods look like this:&lt;/p&gt;
19+
20+
&lt;ul&gt;
21+
&lt;li&gt;
22+
&lt;code&gt;/repos/:owner/:repo/watchers&lt;/code&gt; - A list of users starring the repository.&lt;/li&gt;
23+
&lt;li&gt;
24+
&lt;code&gt;/users/:user/watched&lt;/code&gt; - A list of repositories that a user has starred.&lt;/li&gt;
25+
&lt;li&gt;
26+
&lt;code&gt;/user/watched&lt;/code&gt; - A list of repositories the current user has starred.&lt;/li&gt;
27+
&lt;/ul&gt;&lt;h2 id="phase-1-add-watchers-as-subscriptions"&gt;Phase 1: Add Watchers as Subscriptions&lt;/h2&gt;
28+
29+
&lt;p&gt;In addition to this, we’ll expose Watchers as “Subscriptions”. This is to
30+
keep from clashing with the legacy endpoint.&lt;/p&gt;
31+
32+
&lt;ul&gt;
33+
&lt;li&gt;
34+
&lt;code&gt;/repos/:owner/:repo/subscribers&lt;/code&gt; - A list of users watching the repository.&lt;/li&gt;
35+
&lt;li&gt;
36+
&lt;code&gt;/users/:user/subscribed&lt;/code&gt; - A list of repositories that a user has starred.&lt;/li&gt;
37+
&lt;li&gt;
38+
&lt;code&gt;/user/subscriptions&lt;/code&gt; - A list of repositories the current user is watching.&lt;/li&gt;
39+
&lt;/ul&gt;&lt;p&gt;We’ll also add a copy of the legacy Watchers API in the new endpoint:&lt;/p&gt;
40+
41+
&lt;ul&gt;
42+
&lt;li&gt;
43+
&lt;code&gt;/repos/:owner/:repo/stargazers&lt;/code&gt; - A list of users starring the repository.&lt;/li&gt;
44+
&lt;li&gt;
45+
&lt;code&gt;/users/:user/starred&lt;/code&gt; - A list of repositories that a user has starred.&lt;/li&gt;
46+
&lt;li&gt;
47+
&lt;code&gt;/user/starred&lt;/code&gt; - A list of repositories the current user has starred.&lt;/li&gt;
48+
&lt;/ul&gt;&lt;p&gt;This will be done with the current mime type for the API:&lt;/p&gt;
49+
50+
&lt;pre&gt;&lt;code&gt;application/vnd.github.beta+json
51+
&lt;/code&gt;&lt;/pre&gt;
52+
53+
&lt;p&gt;If you care about your application not breaking, make sure all outgoing API
54+
requests pass that value for the “Accept” header.&lt;/p&gt;
55+
56+
&lt;pre&gt;&lt;code&gt;# Accesses a user's starred repositories.
57+
curl https://api.github.com/user/watched \
58+
-H "Accept: application/vnd.github.beta+json"
59+
&lt;/code&gt;&lt;/pre&gt;
60+
61+
&lt;h2 id="phase-2-switch-watchers-api-endpoint"&gt;Phase 2: Switch &lt;code&gt;/watchers&lt;/code&gt; API Endpoint&lt;/h2&gt;
62+
63+
&lt;p&gt;The “watch” endpoints will now be a copy of the “subscription” endpoints. You
64+
will have to use &lt;code&gt;/user/starred&lt;/code&gt; to get a user’s starred repositories, not
65+
&lt;code&gt;/user/watched&lt;/code&gt;.&lt;/p&gt;
66+
67+
&lt;p&gt;This requires a new mime type value:&lt;/p&gt;
68+
69+
&lt;pre&gt;&lt;code&gt;application/vnd.github.v3+json
70+
&lt;/code&gt;&lt;/pre&gt;
71+
72+
&lt;p&gt;We will release this change in an experimental mode first, letting developers
73+
gracefully upgrade their applications by specifying the new mime value for the
74+
Accept header.&lt;/p&gt;
75+
76+
&lt;pre&gt;&lt;code&gt;# Accesses a user's watched repositories.
77+
curl https://api.github.com/user/watched \
78+
-H "Accept: application/vnd.github.v3+json"
79+
&lt;/code&gt;&lt;/pre&gt;
80+
81+
&lt;h2 id="phase-3-remove-subscribers-api-endpoint"&gt;Phase 3: Remove &lt;code&gt;/subscribers&lt;/code&gt; API Endpoint.&lt;/h2&gt;
82+
83+
&lt;p&gt;This phase involves disabling the subscription endpoints completely. At this
84+
point, you should be using the starring endpoints for starred repositories, and
85+
the watch endpoints for watched repositories.&lt;/p&gt;</content></entry></feed>

‎changes/2012-9-5-watcher-api/index.html‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
5+
<meta http-equiv="Content-Language" content="en-us" />
6+
<meta http-equiv="imagetoolbar" content="false" />
7+
<meta name="MSSmartTagsPreventParsing" content="true" />
8+
<title>Upcoming Changes to Watcher and Star APIs</title>
9+
<link href="/css/reset.css" rel="stylesheet" type="text/css" />
10+
<link href="/css/960.css" rel="stylesheet" type="text/css" />
11+
<link href="/css/uv_active4d.css" rel="stylesheet" type="text/css" />
12+
<link href="/shared/css/documentation.css" media="screen" rel="stylesheet" type="text/css">
13+
<link href="/shared/css/pygments.css" media="screen" rel="stylesheet" type="text/css">
14+
<script src="/shared/js/jquery.js" type="text/javascript"></script>
15+
<script src="/shared/js/documentation.js" type="text/javascript"></script>
16+
</head>
17+
<body class="api">
18+
<div id="header-wrapper">
19+
<div id="header">
20+
<div>
21+
<a class="logo" href="/"><img src="/images/logo_developer.png" width="255" height="45" /></a>
22+
<ul class="nav">
23+
<li><a href="/v3/">API v3</a></li>
24+
<li><a
25+
href="http://support.github.com/discussions/api">Support</a></li>
26+
</ul>
27+
</div>
28+
</div><!-- #header -->
29+
</div><!-- #header-wrapper -->
30+
31+
<div id="wrapper">
32+
<div class="content">
33+
<div class="change" id="/changes/2012-9-5-watcher-api/">
34+
<h2 class="title">
35+
<a href="/changes/2012-9-5-watcher-api/">Upcoming Changes to Watcher and Star APIs</a>
36+
</h2>
37+
38+
<div class="meta">
39+
<div class="who_when">
40+
<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" />
41+
<span class="author vcard fn">
42+
<a href="https://github.com/technoweenie">technoweenie</a>
43+
</span>
44+
<span class="published">
45+
September 5, 2012,
46+
Version: <a href="/changes/v3">v3</a>
47+
</span>
48+
</div>
49+
</div>
50+
51+
52+
<p>We recently <a href="https://github.com/blog/1204-notifications-stars">changed the Watcher behavior</a> on GitHub. What
53+
used to be known as “Watching”, is now “Starring”. Starring is basically
54+
a way to bookmark interesting repositories. Watching is a way to indicate that
55+
you want to receive email or web notifications on a Repository.</p>
56+
57+
<p>This works well on GitHub.com, but poses a problem for the GitHub API. How do
58+
we change this in a way that developers can gracefully upgrade their
59+
applications? We’re currently looking at rolling out the changes in three
60+
phases over an extended period of time.</p>
61+
62+
<h2 id="current-status">Current Status</h2>
63+
64+
<p>The current <a href="http://developer.github.com/v3/repos/watching/">Repository Starring</a> methods look like this:</p>
65+
66+
<ul>
67+
<li>
68+
<code>/repos/:owner/:repo/watchers</code> - A list of users starring the repository.</li>
69+
<li>
70+
<code>/users/:user/watched</code> - A list of repositories that a user has starred.</li>
71+
<li>
72+
<code>/user/watched</code> - A list of repositories the current user has starred.</li>
73+
</ul><h2 id="phase-1-add-watchers-as-subscriptions">Phase 1: Add Watchers as Subscriptions</h2>
74+
75+
<p>In addition to this, we’ll expose Watchers as “Subscriptions”. This is to
76+
keep from clashing with the legacy endpoint.</p>
77+
78+
<ul>
79+
<li>
80+
<code>/repos/:owner/:repo/subscribers</code> - A list of users watching the repository.</li>
81+
<li>
82+
<code>/users/:user/subscribed</code> - A list of repositories that a user has starred.</li>
83+
<li>
84+
<code>/user/subscriptions</code> - A list of repositories the current user is watching.</li>
85+
</ul><p>We’ll also add a copy of the legacy Watchers API in the new endpoint:</p>
86+
87+
<ul>
88+
<li>
89+
<code>/repos/:owner/:repo/stargazers</code> - A list of users starring the repository.</li>
90+
<li>
91+
<code>/users/:user/starred</code> - A list of repositories that a user has starred.</li>
92+
<li>
93+
<code>/user/starred</code> - A list of repositories the current user has starred.</li>
94+
</ul><p>This will be done with the current mime type for the API:</p>
95+
96+
<pre><code>application/vnd.github.beta+json
97+
</code></pre>
98+
99+
<p>If you care about your application not breaking, make sure all outgoing API
100+
requests pass that value for the “Accept” header.</p>
101+
102+
<pre><code># Accesses a user's starred repositories.
103+
curl https://api.github.com/user/watched \
104+
-H "Accept: application/vnd.github.beta+json"
105+
</code></pre>
106+
107+
<h2 id="phase-2-switch-watchers-api-endpoint">Phase 2: Switch <code>/watchers</code> API Endpoint</h2>
108+
109+
<p>The “watch” endpoints will now be a copy of the “subscription” endpoints. You
110+
will have to use <code>/user/starred</code> to get a user’s starred repositories, not
111+
<code>/user/watched</code>.</p>
112+
113+
<p>This requires a new mime type value:</p>
114+
115+
<pre><code>application/vnd.github.v3+json
116+
</code></pre>
117+
118+
<p>We will release this change in an experimental mode first, letting developers
119+
gracefully upgrade their applications by specifying the new mime value for the
120+
Accept header.</p>
121+
122+
<pre><code># Accesses a user's watched repositories.
123+
curl https://api.github.com/user/watched \
124+
-H "Accept: application/vnd.github.v3+json"
125+
</code></pre>
126+
127+
<h2 id="phase-3-remove-subscribers-api-endpoint">Phase 3: Remove <code>/subscribers</code> API Endpoint.</h2>
128+
129+
<p>This phase involves disabling the subscription endpoints completely. At this
130+
point, you should be using the starring endpoints for starred repositories, and
131+
the watch endpoints for watched repositories.</p>
132+
</div>
133+
134+
</div>
135+
136+
<div id="js-sidebar" class="sidebar-shell">
137+
<div class="js-toggle-list sidebar-module expandable">
138+
<ul>
139+
<li class="js-topic">
140+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/">Summary</a></h3>
141+
<ul class="js-guides">
142+
<li><a href="/v3/oauth/">OAuth</a></li>
143+
<li><a href="/v3/mime/">Mime Types</a></li>
144+
<li><a href="/v3/libraries/">Libraries</a></li>
145+
</ul>
146+
</li>
147+
<li class="js-topic">
148+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/gists/">Gists</a></h3>
149+
<ul class="js-guides">
150+
<li><a href="/v3/gists/comments/">Comments</a></li>
151+
</ul>
152+
</li>
153+
<li class="js-topic">
154+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/git/">Git Data</a></h3>
155+
<ul class="js-guides">
156+
<li><a href="/v3/git/blobs/">Blobs</a></li>
157+
<li><a href="/v3/git/commits/">Commits</a></li>
158+
<li><a href="/v3/git/refs/">References</a></li>
159+
<li><a href="/v3/git/tags/">Tags</a></li>
160+
<li><a href="/v3/git/trees/">Trees</a></li>
161+
</ul>
162+
</li>
163+
<li class="js-topic">
164+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/issues/">Issues</a></h3>
165+
<ul class="js-guides">
166+
<li><a href="/v3/issues/assignees/">Assignees</a></li>
167+
<li><a href="/v3/issues/comments/">Comments</a></li>
168+
<li><a href="/v3/issues/events/">Events</a></li>
169+
<li><a href="/v3/issues/labels/">Labels</a></li>
170+
<li><a href="/v3/issues/milestones/">Milestones</a></li>
171+
</ul>
172+
</li>
173+
<li class="js-topic">
174+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/orgs/">Orgs</a></h3>
175+
<ul class="js-guides">
176+
<li><a href="/v3/orgs/members/">Members</a></li>
177+
<li><a href="/v3/orgs/teams/">Teams</a></li>
178+
</ul>
179+
</li>
180+
<li class="js-topic">
181+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/pulls/">Pull Requests</a></h3>
182+
<ul class="js-guides">
183+
<li><a href="/v3/pulls/comments/">Review Comments</a></li>
184+
</ul>
185+
</li>
186+
<li class="js-topic">
187+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/repos/">Repos</a></h3>
188+
<ul class="js-guides">
189+
<li><a href="/v3/repos/collaborators/">Collaborators</a></li>
190+
<li><a href="/v3/repos/comments/">Comments</a></li>
191+
<li><a href="/v3/repos/commits/">Commits</a></li>
192+
<li><a href="/v3/repos/contents/">Contents</a></li>
193+
<li><a href="/v3/repos/downloads/">Downloads</a></li>
194+
<li><a href="/v3/repos/forks/">Forks</a></li>
195+
<li><a href="/v3/repos/keys/">Keys</a></li>
196+
<li><a href="/v3/repos/hooks/">Hooks</a></li>
197+
<li><a href="/v3/repos/merging/">Merging</a></li>
198+
<li><a href="/v3/repos/statuses/">Statuses</a></li>
199+
<li><a href="/v3/repos/watching/">Watching</a></li>
200+
</ul>
201+
</li>
202+
<li class="js-topic">
203+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/users/">Users</a></h3>
204+
<ul class="js-guides">
205+
<li><a href="/v3/users/emails/">Emails</a></li>
206+
<li><a href="/v3/users/followers/">Followers</a></li>
207+
<li><a href="/v3/users/keys/">Keys</a></li>
208+
</ul>
209+
</li>
210+
<li class="js-topic">
211+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/events/">Events</a></h3>
212+
<ul class="js-guides">
213+
<li><a href="/v3/events/types/">Types</a></li>
214+
</ul>
215+
</li>
216+
<li class="js-topic">
217+
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/search/">Search</a></h3>
218+
<ul class="js-guides">
219+
<li><a href="/v3/search/#search-issues">Issues</a></li>
220+
<li><a href="/v3/search/#search-repositories">Repositories</a></li>
221+
<li><a href="/v3/search/#search-users">Users</a></li>
222+
<li><a href="/v3/search/#email-search">Email</a></li>
223+
</ul>
224+
</li>
225+
<li class="js-guides"><h3><a href="/v3/markdown/">Markdown</a></h3></li>
226+
</ul>
227+
</div> <!-- /sidebar-module -->
228+
<div class="sidebar-module">
229+
<p>This website is a <a href="https://github.com/github/developer.github.com" target="_blank">public GitHub repo</a>. Please help us by forking the project and adding to it.</p>
230+
</div>
231+
</div><!-- /sidebar-shell -->
232+
233+
</div><!-- #wrapper -->
234+
235+
<div id="footer" >
236+
<div class="upper_footer">
237+
<div class="footer_inner clearfix">
238+
239+
<!--[if IE]><h4 id="blacktocat_ie">GitHub Links</h4><![endif]-->
240+
<![if !IE]><h4 id="blacktocat">GitHub Links</h4><![endif]>
241+
242+
<ul class="footer_nav">
243+
<h4>GitHub</h4>
244+
<li><a href="https://github.com/about">About</a></li>
245+
<li><a href="https://github.com/blog">Blog</a></li>
246+
<li><a href="https://github.com/features">Features</a></li>
247+
<li><a href="https://github.com/contact">Contact &amp; Support</a></li>
248+
<li><a href="https://github.com/training">Training</a></li>
249+
<li><a href="http://status.github.com/">Site Status</a></li>
250+
</ul>
251+
252+
<ul class="footer_nav">
253+
<h4>Tools</h4>
254+
<li><a href="http://mac.github.com/">GitHub for Mac</a></li>
255+
<li><a href="http://mobile.github.com/">Issues for iPhone</a></li>
256+
<li><a href="https://gist.github.com">Gist: Code Snippets</a></li>
257+
<li><a href="http://enterprise.github.com/">GitHub Enterprise</a></li>
258+
<li><a href="http://jobs.github.com/">Job Board</a></li>
259+
</ul>
260+
261+
<ul class="footer_nav">
262+
<h4>Extras</h4>
263+
<li><a href="http://shop.github.com/">GitHub Shop</a></li>
264+
<li><a href="http://octodex.github.com/">The Octodex</a></li>
265+
</ul>
266+
267+
<ul class="footer_nav">
268+
<h4>Documentation</h4>
269+
<li><a href="http://help.github.com/">GitHub Help</a></li>
270+
<li><a href="http://developer.github.com/">Developer API</a></li>
271+
<li><a href="http://github.github.com/github-flavored-markdown/">GitHub Flavored Markdown</a></li>
272+
<li><a href="http://pages.github.com/">GitHub Pages</a></li>
273+
</ul>
274+
275+
</div><!-- /.site -->
276+
</div><!-- /.upper_footer -->
277+
278+
<div class="lower_footer">
279+
<div class="footer_inner clearfix">
280+
<div id="legal">
281+
<!--[if IE]><a class="home_ie" href="http://github.com">Home</a><![endif]-->
282+
<![if !IE]><a class="home" href="http://github.com">Home</a><![endif]>
283+
284+
<ul id="legal_links">
285+
<li><a href="http://help.github.com/terms-of-service/">Terms of Service</a></li>
286+
<li><a href="http://help.github.com/privacy-policy/">Privacy</a></li>
287+
<li><a href="http://help.github.com/security/">Security</a></li>
288+
</ul>
289+
290+
<p>&copy; <span id="year">year</span> GitHub Inc. All rights reserved.</p>
291+
</div><!-- /#legal or /#legal_ie-->
292+
</div><!-- /.site -->
293+
</div><!-- /.lower_footer -->
294+
</div><!-- /#footer -->
295+
<script type="text/javascript">
296+
var _gauges = _gauges || [];
297+
(function() {
298+
var t = document.createElement('script');
299+
t.type = 'text/javascript';
300+
t.async = true;
301+
t.id = 'gauges-tracker';
302+
t.setAttribute('data-site-id', '4f2038e0cb25bc1b55000003');
303+
t.src = '//secure.gaug.es/track.js';
304+
var s = document.getElementsByTagName('script')[0];
305+
s.parentNode.insertBefore(t, s);
306+
})();
307+
</script>
308+
</body>
309+
</html>

0 commit comments

Comments
 (0)