Notifications REST API#

A notification is a message to be displayed to one or more users. It contains a Message field, which contains the text to be displayed, and optionally a Link field, which is a URL relating to the message.

A notification can also include a Type. The type is used so that something can continually send notifications without duplicating it. For example, the webserver can keep adding the notification Indexer X is down with Type==0xDEADBEEF. The notification engine will just keep updating the old notification, since the type is the same.

Notifications can come in two forms, targeted and broadcast. Broadcast notifications go to everyone, targeted notifications only go to users with the appropriate UID or GID. Broadcast notifications inherently have no UID/GID (they will always be zero).

Note

Only admin users can create notifications visible to other users. Regular users can only create notifications visible to themselves.

Notifications have an Expires field, which specifies a date at which the notification will be automatically deleted. They also have a Sent field, which is typically left blank and auto-populated by the server. There is also an optional IgnoreUntil field; Notifications with a IgnoreUntil date in the future won’t come back on requests until that time. If a notification is added with blank dates (Sent, Expires, IgnoreUntil) they are populated with default values.

Consider the following notification:

{
    "Broadcast": false,
    "Expires": "2019-04-23T03:44:01.776918756-06:00",
    "GID": 0,
    "IgnoreUntil": "0001-01-01T00:00:00Z",
    "Msg": "foobar",
	"Link": "https://gravwell.io",
    "Origin": "00000000-0000-0000-0000-000000000000",
    "Sender": 7,
    "Sent": "2019-04-22T21:44:01.776942432Z",
    "Type": 1,
    "UID": 7
}

This notification is targeted at the user with UID 7 and at no particular group. It was created by the same user. It has a Type of ‘1’. It is not a broadcast notification. It was sent at 21:44 UTC and will expire 12 hours later. The message is “foobar” and has an associated link to https://gravwell.io.

When creating a notification, the only truly required field is Msg. If creating a targeted notification, you must also specify GID and/or UID. The Link and IgnoreUntil fields are optional. The Broadcast flag is set by the server depending on which API endpoint is used.

The “Origin” field is used for automatic notifications generated by indexers and can be ignored.

All notifications are ephemeral. If the webserver/frontend reboots, they are lost.

All notifications have an ID, and each ID monotonically increases and is always represented as a base-10 uint64.

The basic REST APIs URLs are:

/api/notifications
/api/notifications/all/{id:[0-9]+}
/api/notifications/{id:[0-9]+}
/api/notifications/broadcast
/api/notifications/targeted
/api/notifications/targeted/self

Methods for requests:

GET - pull back notifications PUT - update a specific notification POST - add a new notification DELETE - remove a specific notification

Notification rules#

  • Only admins can add new notifications, except via the /api/notifications/targeted/self api.

  • Users can only update notifications that they explicitly own (UIDs match). GID match isn’t enough

  • Users cannot change the UID or GID associated with a notification

  • Users cannot delete notifications they don’t own (UID does not match)

Adding a new notification#

Adding Broadcast or Targeted Notifications (Admin-only)#

Administrators can create broadcast notifications by POSTing a Notification structure to /api/notifications/broadcast or create targeted notifications by POSTing to /api/notifications/targeted. To create a broadcast notification with an explicit type, one might POST the following:

{
	"Msg": "This is a broadcast notification"
	"Type": 123
}

A targeted notification to a particular group might look like this:

{
	"Msg": "This is a targeted notification",
	"GID": 2
}

Adding Self-Targeted Notifications#

Non-admin users can create notifications with a POST to /api/notifications/targeted/self. Note that only the Type, Msg, and Expires fields are respected. These notifications default to a 12 hour expiration; if the Expires field is in the past or more than 24 hours in the future, it will be set to 12 hours from the current time.

{
	"Msg": "This is a self-targeted notification"
}

Getting notifications#

Users can get all their notifications with a GET request to /api/notifications. To get all notifications which were created after a specific notification ID, issue a GET on /api/notifications/{id}. For example if have previously seen notifications 0 through 10, you can make a request for /api/notifications/10 and you will only get NEW notifications that the user has access to.

Fetching All Notifications (Admin-only)#

Admins can get all notifications (irrespective of UID or GID) by issuing a GET on /api/notifications/all/.

Updating a Notification#

To update a notification, do a PUT request on /api/notifications/{id} for the notification in question.

Deleting Notifications#

To delete a notification, send a DELETE request to /api/notifications/{id} for the particular notification ID. Note that non-admin users can only delete notifications explicitly targeted at their UID.