update watching/starring api docs

technoweenie · technoweenie · commit 2e25329d82a8 · 2012-09-06T13:59:45.000-06:00
diff --git a/content/v3/repos/starring.md b/content/v3/repos/starring.md
@@ -0,0 +1,98 @@
+---
+title: Repository Starring | GitHub API
+---
+
+# Repository Starring API
+
+Repository Starring is a feature that lets users bookmark repositories.  Stars
+are shown next to repositories to show an approximate level of interest.  Stars
+have no effect on notifications or the activity feed.  For that, see [Repository
+Watching](/v3/repos/watching).
+
+We recently [changed the way watching
+works](https://github.com/blog/1204-notifications-stars) on GitHub.  Many 3rd
+party applications may be using the "watcher" endpoints for accessing these.
+Starting today, you can start changing these to the new "star" endpoints.  See
+below.
+
+## List Stargazers
+
+    # Using github.v3 media type.
+    GET /repos/:user/:repo/stargazers
+
+    # Legacy, using github.beta media type..
+    GET /repos/:user/:repo/watchers
+
+### Response
+
+<%= headers 200, :pagination => true %>
+<%= json(:user) { |h| [h] } %>
+
+## List repositories being starred
+
+List repositories being starred by a user.
+
+    # Using github.v3 media type.
+    GET /users/:user/starred
+
+    # Legacy, using github.beta media type.
+    GET /users/:user/watched
+
+List repositories being watched by the authenticated user.
+
+    # Using github.v3 media type.
+    GET /user/starred
+
+    # Legacy, using github.beta media type.
+    GET /user/watched
+
+### Response
+
+<%= headers 200, :pagination => true %>
+<%= json(:repo) { |h| [h] } %>
+
+## Check if you are starring a repository
+
+Requires for the user to be authenticated.
+
+    # Using github.v3 media type.
+    GET /user/starred/:user/:repo
+
+    # Legacy, using github.beta media type.
+    GET /user/watched/:user/:repo
+
+### Response if this repository is watched by you
+
+<%= headers 204 %>
+
+### Response if this repository is not watched by you
+
+<%= headers 404 %>
+
+## Star a repository
+
+Requires for the user to be authenticated.
+
+    # Using github.v3 media type.
+    PUT /user/starred/:user/:repo
+
+    # Legacy, using github.beta media type.
+    PUT /user/watched/:user/:repo
+
+### Response
+
+<%= headers 204 %>
+
+## Unstar a repository
+
+Requires for the user to be authenticated.
+
+    # Using github.v3 media type.
+    DELETE /user/starred/:user/:repo
+
+    # Legacy, using github.beta media type.
+    DELETE /user/watched/:user/:repo
+
+### Response
+
+<%= headers 204 %>
diff --git a/content/v3/repos/watching.md b/content/v3/repos/watching.md
@@ -1,69 +1,71 @@
 ---
-title: Repo Watching | GitHub API
+title: Repository Watching | GitHub API
 ---
 
-# Repo Watching API
+# Repository Watching API
+
+Watching a Repository registers the user to receive notificactions on new
+discussions, as well as events in the user's activity feed.  See [Repository
+Starring](/v3/repos/starring) for simple repository bookmarks.
 
 We recently [changed the way watching
-works](https://github.com/blog/1204-notifications-stars) on GitHub. We hope to
-roll out many of these features in the API soon. Until then, the [Watchers
-method](#list-watchers) below will return "stargazers", and the [Watched
-methods](#list-repos-being-watched) return repositories that have been
-"starred."
+works](https://github.com/blog/1204-notifications-stars) on GitHub.  Until 3rd
+party applications stop using the "watcher" endpoints for the current Starring
+API, the Watching API will use the below "subscription" endpoints.
 
 ## List watchers
 
-    GET /repos/:user/:repo/watchers
+    GET /repos/:user/:repo/subscribers
 
 ### Response
 
 <%= headers 200, :pagination => true %>
 <%= json(:user) { |h| [h] } %>
 
-## List repos being watched
+## List repositories being watched
 
-List repos being watched by a user
+List repositories being watched by a user.
 
-    GET /users/:user/watched
+    GET /users/:user/subscriptions
 
-List repos being watched by the authenticated user
+List repositories being watched by the authenticated user.
 
-    GET /user/watched
+    GET /user/subscriptions
 
 ### Response
 
 <%= headers 200, :pagination => true %>
 <%= json(:repo) { |h| [h] } %>
 
-## Check if you are watching a repo
+## Check if you are watching a repository
 
-Requires for the user to be authenticated
+Requires for the user to be authenticated.
 
-    GET /user/watched/:user/:repo
+    GET /user/subscriptions/:user/:repo
 
-### Response if this repo is watched by you
+### Response if this repository is watched by you
 
 <%= headers 204 %>
 
-### Response if this repo is not watched by you
+### Response if this repository is not watched by you
 
 <%= headers 404 %>
 
-## Watch a repo
+## Watch a repository
 
-Requires for the user to be authenticated
+Requires for the user to be authenticated.
 
-    PUT /user/watched/:user/:repo
+    PUT /user/subscriptions/:user/:repo
 
 ### Response
 
 <%= headers 204 %>
 
-## Stop watching a repo
+## Stop watching a repository
 
-Requires for the user to be authenticated
+Requires for the user to be authenticated.
 
-    DELETE /user/watched/:user/:repo
+    DELETE /user/subscriptions/:user/:repo
 
 ### Response
 
diff --git a/layouts/default.html b/layouts/default.html
@@ -95,6 +95,7 @@ <h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/repos/">R
               <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>
