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"
}
}
}
@raskchanky The category is just something that seemed useful in order to distinguish messages that are informational from those that might be considered more important to users, like build failures or dependency rebuilds/promotions -- things a user would probably want to take some action on.
On the dates, I personally like the simplicity of integer timestamps because no timezones or client-side parsing irritations, but if we aren't using them elsewhere, regular ol' ISO date strings are okay, too.
The
message
s will either be submitted by users (e.g., when I promote a package, I might provide an optional message in the dialog or at the CLI describing the reason for that promotion) or by Builder with a webhook callback from GitHub.