sakaiproject/Hilary — pull request #408 by mrvisser (2013-03-07 11:46:45+00:00)
Title: (Notifications) Functional verification PR

Don't code review this. Just making this available so the REST APIs can be
seen and any code planning for UI or related work could happen. These are
the key parts:

**GET /api/notifications** : Get the notification stream of the currently
authenticated user. Takes `start`, `limit`, works like activity stream.
All notifications are **aggregated activities**.

**POST /api/notifications/markRead** : Mark all current notifications for
the authenticated user as read.

**Me Feed:** Now has two extra properties:

`me.extra.notificationsUnread` - A number indicating how many notifications
are unread for the user. If this does not exist on the me feed or is set
to 0, then the user has no notifications. Note this is always a string.

`me.extra.notificationsLastRead` - The timestamp (millis since epoch) in
which the notifications were last read. Also a string. This can be used
to determine which notifications are new, and which are read/acknowledged.
To see only new notifications, start paging from the very start of notifications
and use UI logic to just not display notifications older than the
`notificationsLastRead` time. To see only acknowledged notifications (but why?),
you can use `notificationsLastRead + 1` as the start parameter in the
notifications feed.

There are known race conditions that could cause the notifications to go out of
sync if two notifications are delivered at the same time to the same stream. This
is accepted for now, and is mediated by users marking their notifications as read.