Notification strategy proposal
Issue
As discussed on different occasions, it is of interest for multiple members of the group to have the capability to notify clients about certain events. However, the actual events that may trigger notifications vary substantially as it is deeply according to the businesses of each member. Therefore, it has become apparent that the standard should not foresee specific notifications conditions, at least in the first version.
Nonetheless, it has been agreed that the standard should devise a notification system to be adopted in the implementations of the standard being silent about notification conditions.
Proposal
It the previous meeting, the members pointed out the challenges regarding the incorporation of notifications into the standard and requested for a proposal on the matter.
We summarize here our proposal in three points: strategy, message format, and implementation.
Strategy
The solution we propose the presented demand, building upon the discussions in previous meetings, is the design of an event-driven API based on webhooks.
Webhook defines a strategy for the client to request the server to notify on the occurrence of a certain event (i.e., when a certain criteria is met) using the HTTP protocol. By inform a client URL, the server is able to send POST messages to the client triggered by the conditions selected by the user. Successful cases of webhook implementations include GitHub, Intercom, Stripe, and Slack.
Message Format
Similarly to REST, webhook is a strategy rather than a specific implementation and it is up to us to define how clients can subscribe to notifications. For that reason, we propose here a draft for a subscription message that could be used for subscription messages (already following the hypermedia serialization adopted recently).
{
"links": { ... },
"data": [
{
"resourceType": "/events",
"watchingResources": [
"4231E17139FA49D0BA4C0503DB34E86B",
"732C6A095CF44AACACE7D0F67F3F672D",
"5692257D15984C828F1AC6B6DDC39594"
],
"events": [
"add",
"modify",
"delete"
],
"conditions": [
"opendatahub/event.status.reschedule",
"opendatahub/event.multimediaDescriptions.added"
],
"callbackURL": "https://client.com/callback",
"secret": "xxx123yyy456zzz789",
}
],
}
The message above is an example of a message that could be sent by the client in order to subscribe to notifications provided by a specific implementation where each object in the "data"
array amounts for one subscription. The semantics for each field in the subscription message is the following:
-
"resourceType":
informs the resource type related to the notification subscription according to the available ones (e.g., events, mountainAreas, agents). This field should be MANDATORY. -
"watchingResources":
informs the IDs of the resource desired in case the notification subscription does not apply to the whole set of resources available through the related endpoint. This field should be OPTIONAL. -
"events":
allows informing the basic sorts of events notification subscriptions could refer to. This field should be OPTIONAL. -
"conditions":
Following the same strategy used for implementation-specific event categories, this field allows the specification of implementation-specific notification conditions. In this example, we draw a scenario where Open Data Hub supports notifications on events when they change the status to rescheduled ("opendatahub/event.status.reschedule"
) and when new multimedia descriptions are available ("opendatahub/event.multimediaDescriptions.added"
). This field should be OPTIONAL. -
"callbackURL":
informs the URL the server should use to notify the client on subscribed events. This field should be MANDATORY. -
"secret":
informs the key the server should use as a parameter in notification messages so the client is able to identify the server as a secure source. This field should be MANDATORY.
Implementation
In order to support notifications, the specific implementation should support /api/v1/webhooks
an additional endpoint. In this endpoint, clients should be able to send GET, POST, PATCH and DELETE requests (following the format about) in order to manage their subscriptions.
In this scenario GET requests on the endpoint should return all subscriptions of that should while GET, POST, PATCH and DELETE requests on routes /webhooks/:id
would manage specific subscriptions.