forked from github/developer.github.com
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy path2012-9-5-watcher-api.html
More file actions
88 lines (61 loc) · 3.43 KB
/
Copy path2012-9-5-watcher-api.html
File metadata and controls
88 lines (61 loc) · 3.43 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
---
kind: change
title: Upcoming Changes to Watcher and Star APIs
created_at: 2012-9-5
author_name: technoweenie
---
We recently [changed the Watcher behavior][change-watching] on GitHub. What
used to be known as "Watching", is now "Starring". Starring is basically
a way to bookmark interesting repositories. Watching is a way to indicate that
you want to receive email or web notifications on a Repository.
[change-watching]: https://github.com/blog/1204-notifications-stars
This works well on GitHub.com, but poses a problem for the GitHub API. How do
we change this in a way that developers can gracefully upgrade their
applications? We're currently looking at rolling out the changes in three
phases over an extended period of time.
## Current Status
The current [Repository Starring][starring-api] methods look like this:
* `/repos/:owner/:repo/watchers` - A list of users starring the repository.
* `/users/:user/watched` - A list of repositories that a user has starred.
* `/user/watched` - A list of repositories the current user has starred.
[starring-api]: http://developer.github.com/v3/repos/watching/
## Phase 1: Add Watchers as Subscriptions
This phase exposes Watchers as "Subscriptions". This is to
keep from clashing with the legacy endpoint. This phase will happen
automatically and will not break your application until Phase 3 starts.
* `/repos/:owner/:repo/subscribers` - A list of users watching the repository.
* `/users/:user/subscriptions` - A list of repositories that a user is watching.
* `/user/subscriptions` - A list of repositories the current user is watching.
We'll also add a copy of the legacy Watchers API in the new endpoint:
* `/repos/:owner/:repo/stargazers` - A list of users starring the repository.
* `/users/:user/starred` - A list of repositories that a user has starred.
* `/user/starred` - A list of repositories the current user has starred.
This will be done with the current mime type for the API:
application/vnd.github.beta+json
If you care about your application not breaking, make sure all outgoing API
requests pass that value for the "Accept" header. You should do this now, even
before Phase 1 starts.
# Accesses a user's starred repositories.
curl https://api.github.com/user/watched \
-H "Accept: application/vnd.github.beta+json"
This Phase will be broken once Phase 3 starts. Phase 3 removes all support for
the "beta" mime type, and makes the "v3" mime type the implicit default
for API requests.
## Phase 2: Switch `/watchers` API Endpoint
The "watch" endpoints will now be a copy of the "subscription" endpoints. You
will have to use `/user/starred` to get a user's starred repositories, not
`/user/watched`.
This requires a new mime type value:
application/vnd.github.v3+json
This is a breaking change from Phase 1. We will release this change in an
experimental mode first, letting developers gracefully upgrade their
applications by specifying the new mime value for the Accept header.
# Accesses a user's watched repositories.
curl https://api.github.com/user/watched \
-H "Accept: application/vnd.github.v3+json"
## Phase 3: Remove `/subscribers` API Endpoint.
This phase involves disabling the subscription endpoints completely. At this
point, you should be using the starring endpoints for starred repositories, and
the watch endpoints for watched repositories.
Keep on passing the "v3" mimetype in your application, until the API has
another breaking change to make.