Skip to content

Commit 7b79e9f

Browse files
technoweenietechnoweenie
committed
Merge branch 'watcher-docs'
2 parents d7a5f82 + f28c4e4 commit 7b79e9f

File tree

4 files changed

+154
-36
lines changed

4 files changed

+154
-36
lines changed

content/v3/mime.md renamed to content/v3/media.md

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
---
2-
title: Custom Mime Types | GitHub API
2+
title: Custom Media Types | GitHub API
33
---
44

5-
# GitHub Mime Types
5+
# GitHub Media Types
66

7-
Custom mime types are used in the API to let consumers choose the format
7+
Custom media types are used in the API to let consumers choose the format
88
of the data they wish to receive. This is done by adding one or more of
9-
the following types to the `Accept` header when you make a request. Mime
10-
types are specific to resources, allowing them to change independently
11-
and support formats that other resources don't.
9+
the following types to the `Accept` header when you make a request. Media types
10+
are specific to resources, allowing them to change independently and support
11+
formats that other resources don't.
1212

13-
All GitHub mime types look like this:
13+
All GitHub media types look like this:
1414

1515
application/vnd.github[.version].param[+json]
1616

17-
The most basic mime types the API supports are:
17+
The most basic media types the API supports are:
1818

1919
application/json
2020
application/vnd.github+json
@@ -30,20 +30,37 @@ put the version before the property:
3030

3131
application/vnd.github.beta.raw+json
3232

33+
You can check the current version through every response's headers. Look
34+
for the `X-GitHub-Media-Type` header:
35+
36+
$ curl https://api.github.com/users/technoweenie -I
37+
HTTP/1.1 200 OK
38+
X-GitHub-Media-Type: github.beta
39+
40+
$ curl https://api.github.com/users/technoweenie -I \
41+
-H "Accept: application/vnd.github.full+json"
42+
HTTP/1.1 200 OK
43+
X-GitHub-Media-Type: github.beta; param=full; format=json
44+
45+
$ curl https://api.github.com/users/technoweenie -I \
46+
-H "Accept: application/vnd.github.v3.full+json"
47+
HTTP/1.1 200 OK
48+
X-GitHub-Media-Type: github.v3; param=full; format=json
49+
3350
For specifics on versions, check the [API changelog](/v3/changelog).
3451

3552
## Comment Body Properties
3653

3754
The body of a comment can be written in [GitHub Flavored Markdown][gfm].
3855
Issues, Issue Comments, Pull Request Comments, and Gist Comments all
39-
accept these same mime types:
56+
accept these same media types:
4057

4158
### Raw
4259

4360
application/vnd.github.VERSION.raw+json
4461

4562
Return the raw markdown body. Response will include `body`. This is the
46-
default if you do not pass any specific mime type.
63+
default if you do not pass any specific media type.
4764

4865
### Text
4966

@@ -68,7 +85,7 @@ Return raw, text and html representations. Response will include `body`,
6885

6986
## Git Blob Properties
7087

71-
The following mime types are allowed when getting a blob:
88+
The following media types are allowed when getting a blob:
7289

7390
### JSON
7491

‎content/v3/repos/starring.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: Repository Starring | GitHub API
3+
---
4+
5+
# Repository Starring API
6+
7+
Repository Starring is a feature that lets users bookmark repositories. Stars
8+
are shown next to repositories to show an approximate level of interest. Stars
9+
have no effect on notifications or the activity feed. For that, see [Repository
10+
Watching](/v3/repos/watching).
11+
12+
We recently [changed the way watching
13+
works](https://github.com/blog/1204-notifications-stars) on GitHub. Many 3rd
14+
party applications may be using the "watcher" endpoints for accessing these.
15+
Starting today, you can start changing these to the new "star" endpoints. See
16+
below.
17+
18+
## List Stargazers
19+
20+
# Using github.v3 media type.
21+
GET /repos/:user/:repo/stargazers
22+
23+
# Legacy, using github.beta media type..
24+
GET /repos/:user/:repo/watchers
25+
26+
### Response
27+
28+
<%= headers 200, :pagination => true %>
29+
<%= json(:user) { |h| [h] } %>
30+
31+
## List repositories being starred
32+
33+
List repositories being starred by a user.
34+
35+
# Using github.v3 media type.
36+
GET /users/:user/starred
37+
38+
# Legacy, using github.beta media type.
39+
GET /users/:user/watched
40+
41+
List repositories being watched by the authenticated user.
42+
43+
# Using github.v3 media type.
44+
GET /user/starred
45+
46+
# Legacy, using github.beta media type.
47+
GET /user/watched
48+
49+
### Response
50+
51+
<%= headers 200, :pagination => true %>
52+
<%= json(:repo) { |h| [h] } %>
53+
54+
## Check if you are starring a repository
55+
56+
Requires for the user to be authenticated.
57+
58+
# Using github.v3 media type.
59+
GET /user/starred/:user/:repo
60+
61+
# Legacy, using github.beta media type.
62+
GET /user/watched/:user/:repo
63+
64+
### Response if this repository is watched by you
65+
66+
<%= headers 204 %>
67+
68+
### Response if this repository is not watched by you
69+
70+
<%= headers 404 %>
71+
72+
## Star a repository
73+
74+
Requires for the user to be authenticated.
75+
76+
# Using github.v3 media type.
77+
PUT /user/starred/:user/:repo
78+
79+
# Legacy, using github.beta media type.
80+
PUT /user/watched/:user/:repo
81+
82+
### Response
83+
84+
<%= headers 204 %>
85+
86+
## Unstar a repository
87+
88+
Requires for the user to be authenticated.
89+
90+
# Using github.v3 media type.
91+
DELETE /user/starred/:user/:repo
92+
93+
# Legacy, using github.beta media type.
94+
DELETE /user/watched/:user/:repo
95+
96+
### Response
97+
98+
<%= headers 204 %>

‎content/v3/repos/watching.md‎

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,71 @@
11
---
2-
title: Repo Watching | GitHub API
2+
title: Repository Watching | GitHub API
33
---
44

5-
# Repo Watching API
5+
# Repository Watching API
6+
7+
Watching a Repository registers the user to receive notificactions on new
8+
discussions, as well as events in the user's activity feed. See [Repository
9+
Starring](/v3/repos/starring) for simple repository bookmarks.
610

711
We recently [changed the way watching
8-
works](https://github.com/blog/1204-notifications-stars) on GitHub. We hope to
9-
roll out many of these features in the API soon. Until then, the [Watchers
10-
method](#list-watchers) below will return "stargazers", and the [Watched
11-
methods](#list-repos-being-watched) return repositories that have been
12-
"starred."
12+
works](https://github.com/blog/1204-notifications-stars) on GitHub. Until 3rd
13+
party applications stop using the "watcher" endpoints for the current Starring
14+
API, the Watching API will use the below "subscription" endpoints.
1315

1416
## List watchers
1517

16-
GET /repos/:user/:repo/watchers
18+
GET /repos/:user/:repo/subscribers
1719

1820
### Response
1921

2022
<%= headers 200, :pagination => true %>
2123
<%= json(:user) { |h| [h] } %>
2224

23-
## List repos being watched
25+
## List repositories being watched
2426

25-
List repos being watched by a user
27+
List repositories being watched by a user.
2628

27-
GET /users/:user/watched
29+
GET /users/:user/subscriptions
2830

29-
List repos being watched by the authenticated user
31+
List repositories being watched by the authenticated user.
3032

31-
GET /user/watched
33+
GET /user/subscriptions
3234

3335
### Response
3436

3537
<%= headers 200, :pagination => true %>
3638
<%= json(:repo) { |h| [h] } %>
3739

38-
## Check if you are watching a repo
40+
## Check if you are watching a repository
3941

40-
Requires for the user to be authenticated
42+
Requires for the user to be authenticated.
4143

42-
GET /user/watched/:user/:repo
44+
GET /user/subscriptions/:user/:repo
4345

44-
### Response if this repo is watched by you
46+
### Response if this repository is watched by you
4547

4648
<%= headers 204 %>
4749

48-
### Response if this repo is not watched by you
50+
### Response if this repository is not watched by you
4951

5052
<%= headers 404 %>
5153

52-
## Watch a repo
54+
## Watch a repository
5355

54-
Requires for the user to be authenticated
56+
Requires for the user to be authenticated.
5557

56-
PUT /user/watched/:user/:repo
58+
PUT /user/subscriptions/:user/:repo
5759

5860
### Response
5961

6062
<%= headers 204 %>
6163

62-
## Stop watching a repo
64+
## Stop watching a repository
6365

64-
Requires for the user to be authenticated
66+
Requires for the user to be authenticated.
6567

66-
DELETE /user/watched/:user/:repo
68+
DELETE /user/subscriptions/:user/:repo
6769

6870
### Response
6971

‎layouts/default.html‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
<h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/">Summary</a></h3>
4646
<ul class="js-guides">
4747
<li><a href="/v3/oauth/">OAuth</a></li>
48-
<li><a href="/v3/mime/">Mime Types</a></li>
48+
<li><a href="/v3/media/">Media Types</a></li>
4949
<li><a href="/v3/libraries/">Libraries</a></li>
5050
</ul>
5151
</li>
@@ -100,6 +100,7 @@ <h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/repos/">R
100100
<li><a href="/v3/repos/keys/">Keys</a></li>
101101
<li><a href="/v3/repos/hooks/">Hooks</a></li>
102102
<li><a href="/v3/repos/merging/">Merging</a></li>
103+
<li><a href="/v3/repos/starring/">Starring</a></li>
103104
<li><a href="/v3/repos/statuses/">Statuses</a></li>
104105
<li><a href="/v3/repos/watching/">Watching</a></li>
105106
</ul>

0 commit comments

Comments
 (0)