Based on current designs, we need new APIs that support retrieving lists of notifications, filtered by the requesting user, that allow for:
- Listing all recent (e.g., most recent 50) notifications, grouped by origin.
- Listing all notifications within an origin, with optional paging.
- Deleting all notifications, irrespective of origin.
- Deleting all notifications within an origin.
- Deleting a single notification.
With that need, I'm thinking of the following new endpoints, respectively:
GET /notifications
GET /notifications/:origin (with optional ?range=50)
DELETE /notifications
DELETE /notifications/:origin
DELETE /notifications/:origin/:id
Technically we shouldn't need the origin for that last one, but I've included it to more easily differentiate it from DELETE /notifications/:origin
.
Note that ...body
below represents the body of a notification message, which could take different forms, each of which is detailed in Example Notification Bodies below.
GET /notifications
[
{
origin: "core",
notifications: [
{
...body
},
{
...body
}
]
},
{
origin: "cnunciato",
notifications: [
{
...body
}
]
}
]
GET /notifications/:origin
{
range_start: 0,
range_end: 49,
total_count: 123,
data: [
{
...body
},
{
...body
}
]
}
DELETE /notifications
-> 204
DELETE /notifications/:origin
-> 204
DELETE /notifications/:origin/:id
-> 204
Initally we're interested in the following set of notifications:
- Builder started building a package in one of my origins, based on a GitHub webhook.
- Builder built (or failed to build) a package in one of my origins.
- Builder promoted a package in one of my origins (e.g., to the unstable channel, after a build).
- A user promoted a package in one of my origins.
- A user demoted a package in one of my origins.
- A user submitted a build request for a package in one of my origins.
- A user uploaded a package to one of my origins.
- A package that is a dependency of one of the packages in any of my origins was promoted to stable.
Suggested responses for these are enumerated below.
{
id: 1234567890,
timestamp: 1512687331658,
type: "job-started",
category: "info",
origin: "core",
data: {
package: "node"
group_id: "12345",
job_id: "67890",
status: "Processing",
source: "vcs:github",
message: "This is the first line of the commit message"
}
}
{
id: 1234567890,
timestamp: 1512687331658,
type: "job-finished",
category: "error",
origin: "core",
data: {
package: "node",
version: "1.2.3",
release: "2017010100000000",
group_id: "12345",
job_id: "67890",
status: "Failed",
source: "vcs:github",
message: "This is the first line of the commit message",
}
}
{
id: 1234567890,
timestamp: 1512687331658,
type: "package-promoted",
category: "info",
origin: "core",
data: {
package: "node",
version: "1.2.3",
release: "2017010100000000",
source: "bldr",
channel: "unstable"
}
}
{
id: 1234567890,
timestamp: 1512687331658,
type: "package-promoted",
category: "info",
origin: "core",
data: {
package: "node",
version: "1.2.3",
release: "2017010100000000",
channel: "stable",
source: "user:cnunciato",
message: "Releasing! Yay!"
}
}
{
id: 1234567890,
timestamp: 1512687331658,
type: "package-demoted",
category: "warning",
origin: "core",
data: {
package: "node",
version: "1.2.3",
release: "2017010100000000",
channel: "stable",
source: "user:cnunciato",
message: "Some stuff happened, so we had to demote."
}
}
{
id: 1234567890,
timestamp: 1512687331658,
type: "job-scheduled",
category: "info",
origin: "core",
data: {
package: "node"
group_id: "12345",
job_id: "67890",
source: "user:cnunciato",
message: "Do we feel like a message might be useful here, too?"
}
}
{
id: 1234567890,
timestamp: 1512687331658,
type: "package-uploaded",
category: "info",
origin: "core",
data: {
package: "node",
version: "1.2.3",
release: "2017010100000000",
channel: "unstable",
source: "user:cnunciato"
}
}
{
id: 1234567890,
timestamp: 1512687331658,
type: "dep-promoted",
category: "info",
origin: "core",
data: {
package: "node",
version: "1.2.3",
release: "2017010100000000",
channel: "stable",
dependent: {
origin: "cnunciato",
name: "ghost,
version: "1.2.3",
release: "2017010100000000"
}
}
}
This looks like a good start. There are some additional things to discuss and close on before we commit to an API since this will potentially have a huge impact on the service scalability (eg, we need to decide on how/where we are going to store the activity feed, what model we are going to use to build it (read time vs. write time), what front end we will use for notifications, etc).
For the API, the main issue I see is that this proposal looks like a polled model. We might want to consider investigating whether we we should design around a 'web push' model instead. That decision will also inform the overall architecture of the notification solution.