Skip to content

Commit 1aa03a7

Browse files
technoweenietechnoweenie
committed
document notification format
1 parent 4e8c35e commit 1aa03a7

File tree

3 files changed

+147
-21
lines changed

3 files changed

+147
-21
lines changed

‎content/v3/activity/notifications.md‎

Lines changed: 65 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ user is involved including:
2323
* Commits the user authors or commits
2424
* Any discussion in which the user actively participates
2525

26+
Notifications come back as Summary objects. A Summary contains information
27+
about the current discussion of an Issue/PullRequest/Commit.
2628

2729
## List your notifications
2830

@@ -39,6 +41,10 @@ participating
3941
: _Optional_ **boolean** `true` to show only notifications in which the user is
4042
directly participating or mentioned.
4143

44+
### Response
45+
46+
<%= headers 200 %>
47+
<%= json(:summary) { |h| [h] } %>
4248

4349
## List your notifications in a repository
4450

@@ -55,39 +61,90 @@ participating
5561
: _Optional_ **boolean** `true` to show only notifications in which the user is
5662
directly participating or mentioned.
5763

64+
### Response
65+
66+
<%= headers 200 %>
67+
<%= json(:summary) { |h| [h] } %>
68+
5869
## Mark as read
5970

6071
Marking a notification as "read" archives it removes it from the [default view
6172
on GitHub.com](https://github.com/notifications).
6273

6374
POST /notifications/mark
6475

76+
### Response
77+
78+
<%= headers 205 %>
79+
6580
## Mark notifications as read in a repository
6681

6782
Marking all notification in a repository as "read" archives them removes them
6883
from the [default view on GitHub.com](https://github.com/notifications).
6984

7085
POST /repos/:owner/:repo/notifications/mark
7186

87+
### Response
88+
89+
<%= headers 205 %>
90+
7291
## View a single summary
7392

7493
GET /notifications/summaries/:id
7594

95+
### Response
96+
97+
<%= headers 200 %>
98+
<%= json(:summary) { |h| [h] } %>
99+
76100
## Mark a summary as read
77101

78102
POST /notifications/summaries/:id/mark
79103

80-
## Mute a summary
104+
### Response
105+
106+
<%= headers 205 %>
107+
108+
## Get a Summary Subscription
109+
110+
This checks to see if the current user is subscribed to a summary. You can also
111+
[get a Repository subscription](http://localhost:3000/v3/activity/watching/#get-a-repository-subscription).
112+
113+
GET /notifications/summary/1/subscription
114+
115+
### Response
116+
117+
<%= headers 200 %>
118+
<%= json :subscription %>
119+
120+
## Set a Summary Subscription
121+
122+
This lets you subscribe to a summary, or ignore it. Subscribing to a summary
123+
is unnecessary if the user is already subscribed to the repository. Ignoring
124+
a summary will mute all future notifications (until you comment or get
125+
@mentioned).
126+
127+
PUT /notifications/summary/1/subscription
128+
129+
### Input
130+
131+
subscribed
132+
: **boolean** Determines if notifications should be received from this
133+
repository.
134+
135+
ignored
136+
: **boolean** Deterimines if all notifications should be blocked from this
137+
repository.
81138

82-
Muting a thread prevents future notifications from being sent for a discussion
83-
summary.
139+
### Response
84140

85-
POST /notifications/summaries/:id/mute
141+
<%= headers 200 %>
142+
<%= json :subscription %>
86143

87-
## Unmute a summary
144+
## Delete a Summary Subscription
88145

89-
Muting a thread enables future notifications from being sent for a discussion
90-
summary.
146+
DELETE /notifications/summary/1/subscription
91147

92-
POST /notifications/summaries/:id/unmute
148+
### Response
93149

150+
<%= headers 204 %>

‎content/v3/activity/watching.md‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,43 @@ List repositories being watched by the authenticated user.
4141
<%= headers 200, :pagination => true %>
4242
<%= json(:repo) { |h| [h] } %>
4343

44-
## Check if you are watching a repository
44+
## Get a Repository Subscription
45+
46+
GET /repos/:owner/:repo/subscription
47+
48+
### Response
49+
50+
<%= headers 200 %>
51+
<%= json :subscription %>
52+
53+
## Set a Repository Subscription
54+
55+
PUT /repos/:owner/:repo/subscription
56+
57+
### Input
58+
59+
subscribed
60+
: **boolean** Determines if notifications should be received from this
61+
repository.
62+
63+
ignored
64+
: **boolean** Deterimines if all notifications should be blocked from this
65+
repository.
66+
67+
### Response
68+
69+
<%= headers 200 %>
70+
<%= json :subscription %>
71+
72+
## Delete a Repository Subscription
73+
74+
DELETE /repos/:owner/:repo/subscription
75+
76+
### Response
77+
78+
<%= headers 204 %>
79+
80+
## Check if you are watching a repository (LEGACY)
4581

4682
Requires for the user to be authenticated.
4783

@@ -55,7 +91,7 @@ Requires for the user to be authenticated.
5591

5692
<%= headers 404 %>
5793

58-
## Watch a repository
94+
## Watch a repository (LEGACY)
5995

6096
Requires for the user to be authenticated.
6197

@@ -65,7 +101,7 @@ Requires for the user to be authenticated.
65101

66102
<%= headers 204 %>
67103

68-
## Stop watching a repository
104+
## Stop watching a repository (LEGACY)
69105

70106
Requires for the user to be authenticated.
71107

‎lib/resources.rb‎

Lines changed: 43 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -139,23 +139,26 @@ def text_html(response, status, head = {})
139139
"key" => "ssh-rsa AAA...",
140140
}
141141

142-
REPO = {
142+
SIMPLE_REPO = {
143+
"id" => 1296269,
144+
"owner" => USER,
145+
"name" => "Hello-World",
146+
"full_name" => "octocat/Hello-World",
147+
"description" => "This your first repo!",
148+
"private" => false,
149+
"fork" => false,
143150
"url" => "https://api.github.com/repos/octocat/Hello-World",
144-
"html_url" => "https://github.com/octocat/Hello-World",
151+
"html_url" => "https://github.com/octocat/Hello-World"
152+
}
153+
154+
REPO = SIMPLE_REPO.merge({
145155
"clone_url" => "https://github.com/octocat/Hello-World.git",
146156
"git_url" => "git://github.com/octocat/Hello-World.git",
147157
"ssh_url" => "[email protected]:octocat/Hello-World.git",
148158
"svn_url" => "https://svn.github.com/octocat/Hello-World",
149159
"mirror_url" => "git://git.example.com/octocat/Hello-World",
150-
"id" => 1296269,
151-
"owner" => USER,
152-
"name" => "Hello-World",
153-
"full_name" => "octocat/Hello-World",
154-
"description" => "This your first repo!",
155160
"homepage" => "https://github.com",
156161
"language" => nil,
157-
"private" => false,
158-
"fork" => false,
159162
"forks" => 9,
160163
"forks_count" => 9,
161164
"watchers" => 80,
@@ -166,7 +169,7 @@ def text_html(response, status, head = {})
166169
"pushed_at" => "2011-01-26T19:06:43Z",
167170
"created_at" => "2011-01-26T19:01:12Z",
168171
"updated_at" => "2011-01-26T19:14:43Z"
169-
}
172+
})
170173

171174
FULL_REPO = REPO.merge({
172175
"organization" => USER.merge('type' => 'Organization'),
@@ -957,6 +960,36 @@ def text_html(response, status, head = {})
957960
:sha => "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15",
958961
:size => 100
959962
}
963+
964+
SUMMARY = {
965+
:id => 1,
966+
:repository => SIMPLE_REPO,
967+
:thread => {
968+
:type => "Issue",
969+
:id => 123,
970+
:title => "Greetings",
971+
:state => 'open',
972+
:number => 123
973+
},
974+
:comment => {
975+
:type => "IssueComment",
976+
:id => 123,
977+
:body => "Hello",
978+
:user => USER,
979+
:created_at => '2012-09-25T07:54:41-07:00',
980+
},
981+
:reason => 'subscribed',
982+
:unread => true,
983+
:updated_at => '2012-09-25T07:54:41-07:00',
984+
:last_read_at => '2012-09-25T07:54:41-07:00'
985+
}
986+
987+
SUBSCRIPTION = {
988+
:subscribed => true,
989+
:ignored => false,
990+
:reason => nil,
991+
:created_at => "2012-10-06T21:34:12Z"
992+
}
960993
end
961994
end
962995

0 commit comments

Comments
 (0)