Meldingen en de openbare endpoints van OpenPlatform

Naast de start en de verificatie heeft OpenPlatform enkele endpoints voor de toepassingen en voor andere systemen. Ze staan in controllers/verify.js, controllers/api.js en controllers/socket.js.

Een melding sturen

Het antwoord van de verificatie bevat notify, een adres van de vorm <platform url>/notify/?token=<checksum of user and application>, wanneer de gebruiker meldingen accepteert. De toepassing stuurt er een POST naartoe met de header x-token en een JSON-body:

Veld	Betekenis
body	de tekst van de melding
path	het pad binnen de toepassing dat de melding opent
icon, color	optioneel: ze vervangen het icoon en de kleur van de toepassing

De waarde van x-token is het meldingstoken dat OpenPlatform voor die gebruiker en toepassing afleidt: de MD5 van het meldingsadres met de reqtoken van de toepassing als salt, en de MD5 van dat resultaat met haar restoken als salt (FUNC.makenotify in definitions/func.js). Beide geheimen zijn dezelfde die de toepassing voor de start deelt (een app registreren).

OpenPlatform antwoordt Invalid token wanneer de controlesom of de header niet klopt, en Not allowed notifications wanneer de gebruiker of de toepassing ze niet accepteert. Het controleert ook de toegestane adressen van de toepassing en dat de gebruiker bevestigd, ingeschakeld en actief is. Wanneer alles klopt:

1. slaat het de melding op (tabel tbl_notification) en verhoogt de teller van ongelezen meldingen van de gebruiker;
2. werkt het de sessies van die gebruiker bij die in het portaal open zijn, zodat de teller meteen verschijnt;
3. publiceert het Notifications.create via TMS wanneer de instelling $tms aan staat;
4. geeft het de identificatie van de melding terug.

Voor gebruikers die offline zijn en ongelezen meldingen hebben, stuurt een servicetaak een e-mailsamenvatting ("Unread notifications") wanneer de mailinstellingen zijn geconfigureerd, hooguit eens per drie dagen per gebruiker (definitions/init.js).

De gebruikers-API (een token)

GET /users/ geeft de groepen en de gebruikers van het platform als JSON. Het is uitgeschakeld totdat de instellingen allow_token en token zijn ingesteld. De aanroeper stuurt het token als queryparameter token of als header x-token; herhaalde verkeerde pogingen worden geblokkeerd. De gebruikers komen zonder geheimen: identificatie, referentie, taal, geslacht, foto (een absoluut adres), naam, e-mail, kleur, voorkeuren, vlaggen (sa, isdisabled, isinactive, isonline), datums en de id’s van hun groepen.

Een afbeelding uploaden

POST /upload/base64/ (tot 2 MB) accepteert een JSON-body met de bestandsnaam en file als data-URI, en alleen JPEG. Het heeft een aangemelde gebruiker nodig of het querytoken van de instelling servicetoken (zie instellingen en database voor waar die sleutel vandaan komt). De afbeelding wordt opgeslagen in de bestandsopslag files en het antwoord is haar adres, /files/<id and checksum>.jpg; het adres werkt alleen met de controlesom.

Meerdere instanties: de synchronisatiesocket

SOCKET /sync/ verbindt instanties van OpenPlatform. Een client wordt geaccepteerd wanneer de instelling sync aan staat en het token van de query gelijk is aan sync_token; elke andere client wordt een halve seconde na het openen gesloten met de code 4001. De berichten van een bevestigde client worden doorgestuurd naar de anderen, en terwijl een bevestigde client opnieuw verbinding maakt, worden de berichten tot tien seconden in de wachtrij gezet.