Notifications RESTful API

Overview

Connection with JpaNotificationService

This API is strongly tied to another proposed enhancement:  the JpaNotificationService described on another page.  This API describes both read operations (via. GET requests) as well as write operations (POST and/or PUT).  Without the JpaNotificationService, there would be nothing in the Notification portlet to write to, and that is the nature of this strong correlation.

Notification

The notification entity represents a single notification for a single user.  The core notification should be generic enough that they are easy to generate and work with, but provide enough flexibility that it allows for extensibility and allows for customized metadata.   The Notification entity will contain only a handful of strongly-typed fields.   The strongly typed fields should include Title, Date, Body, Severity and possibly an image URL.  Severity should be a predefined list of concrete severity values (eg.  URGENT, IMPORTANT, INFORMATION).

Any additional notification data should be stored as a notification attribute.  The notification attributes will be a set of name-value pairs.   The name will be a string identifier and the value will be a list of String values.   Interpretation of the Notification attributes will be largely left to the notification producers and consumers.   Producers in this case are data sources – concrete implementations of INotificationService.  Consumers are view strategies – typically JSP files built & deployed with the Notification war and selected in the portlet publication record.  The intent of notification attributes is to allow notification producers to augment the base/simple notification with additional notification specific information without introducing API-level changes that may be incompatible with existing integrations, etc.

Notifications will also support notification states.   The notification states provide a immutable log of the state of the notification.  The API will support adding additional states to any notification record, but will disallow modifying or deleting a state once it has been added.   Each state will include a verb that indicates what occurred and a timestamp.  Each notification will contain a set of states.   Examples of the type of information that would be stored in a notification state would be:  Notification was “sent” on Jan 12, 2015.   In this case the verb is “sent”.   Or, notification was “read” on Jan 13, 2015.

Adding state information is the notification consumers responsibility.  Notification consumers should make a best effort to provide meaningful state information when available. but it is not a requirement.  For instance, it is not a requirement that a SMS consumer be able to create a “read” state event when the end-user reads the notification.    The one state that every behaving state implementation should support is “sent”.   After a notification has been processed every consumer should create a “sent” state to indicate that the event has been processed.    It may make sense to enumerate the set of allowable verbs to simplify reporting and management.

Notification Interface

All API interfaces will be defined to use a RESTful interface.    The notification REST APIs will attempt to follow REST best practices where possible.   In all cases, the REST API should return a status code in the 200-299 range on success and return an appropriate HTTP status code in the case of an error.   All interfaces should work correctly with JSON or XML based on HTTP headers.

All REST endpoints should be versioned.  Changes that introduce backwards incompatible changes should update the version number.

Note: all URLs are suggested, but are subject to change.

Notification API

For initial implementation, the notification interface will need to support POST and GET. 

Create new notification:

Retrieve an existing notification:

In future designs, it may be desirable to add a PUT and a DELETE method that would allow notifications to be modified.  Because it only makes sense to modify or delete notifications that have not yet been delivered, that would probably require support for scheduling notifications to be delivered at some future time.   For the initial implementation, the notification service will not support that feature.

Notification States API

The notification states API will provide a RESTful API to attach state information to a notification.   It will also support reading state information for any notification as well as overall reporting of notification by state.

Add a new state:

Get all Notification states for a single Notification

Get a single notification state

There will be no PUT or DELETE REST API.

Reporting API

The reporting API will allow administrators to get an overview of notifications.    Need to develop better requirements on the type of reporting that is needed.

Profile

The profile entity represents a single user profile.   The profile will include a simple map that allows each user to customize how they will receive notifications.   The profile will need to support setting a default notification method and then overriding the default notification method by severity.   For instance, a user may choose to have all URGENT notifications delivered to their phone via SMS, but only view notifications with lower severity levels in the portal.    Since the portal will not be providing the actual notification support, the entity should be designed in a way to allow for extensibility.   Each severity should support multiple  notification methods.    Because the portal will not implement the actual push notification, the uPortal entities must be defined in a flexible enough way that the profile can be easily extended.   For instance, an email profile may only need a email address setting stored with the profile, but an SMS profile may need to store the carrier and the number.

Profile API

TODO:  Should API provide a GET /notification-profile/users/{user-id}/severity/{severity} that makes it easier to fetch all notifications that apply for a message.   In other words, a delivery service could grab a message, look at the severity and user-id, then GET this URL to just fetch the profiles that they care about vs. having to GET /notification-profile/users/{user-id}/profiles and then filter the delivery methods by severity.