Notifications and the public endpoints of OpenPlatform

Besides the launch and the verification, OpenPlatform has a few endpoints for the applications and for other systems. They are in controllers/verify.js, controllers/api.js and controllers/socket.js.

Send a notification

The answer of the verification contains notify, an address of the form <platform url>/notify/?token=<checksum of user and application>, when the user accepts notifications. The application sends a POST to it with the header x-token and a JSON body:

Field	Meaning
body	the text of the notification
path	the path inside the application that the notification opens
icon, color	optional: they replace the icon and the colour of the application

The value of x-token is the notify token that OpenPlatform derives for that user and application: the MD5 of the notify address salted with the reqtoken of the application, and the MD5 of that result salted with its restoken (FUNC.makenotify in definitions/func.js). Both secrets are the same ones that the application shares for the launch (register an app).

OpenPlatform answers Invalid token when the checksum or the header do not match, and Not allowed notifications when the user or the application does not accept them. It also checks the allowed addresses of the application and that the user is confirmed, enabled and active. When everything is right it:

1. stores the notification (table tbl_notification) and increases the unread counter of the user;
2. updates the sessions of that user that are open in the portal, so the counter appears at once;
3. publishes Notifications.create by TMS when the setting $tms is on;
4. returns the identifier of the notification.

For users that are offline and have unread notifications, a service job sends an email digest ("Unread notifications") when the mail settings are configured, at most once every three days per user (definitions/init.js).

The users API (a token)

GET /users/ returns the groups and the users of the platform as JSON. It is disabled until the settings allow_token and token are set. The caller sends the token as the query parameter token or as the header x-token; repeated wrong tries are blocked. The users come without secrets: identifier, reference, language, gender, photo (an absolute address), name, email, colour, preferences, flags (sa, isdisabled, isinactive, isonline), dates and the ids of their groups.

Upload an image

POST /upload/base64/ (up to 2 MB) accepts a JSON body with the file name and file as a data URI, and only JPEG. It needs a signed-in user or the query token of the setting servicetoken (see settings and database for where that key comes from). The image is stored in the file storage files and the answer is its address, /files/<id and checksum>.jpg; the address only works with the checksum.

Several instances: the sync socket

SOCKET /sync/ connects instances of OpenPlatform. A client is accepted when the setting sync is on and the query token equals sync_token; any other client is closed with the code 4001 half a second after opening. The messages of a confirmed client are relayed to the others, and while a confirmed client is reconnecting the messages are queued for up to ten seconds.