Services API
The Services API allows external parties (e.g. plugins) to access core platform functionality, such as sending push notifications or adding notifications to the Notification Center.
Clients
The Services API is organized around the concept of clients. Each external system that wants to use the API is called a client. Clients are configured in the Relevance dashboard. Each client is granted access to specific services for specific magazines.
Making requests
The Services API is secured using JSON Web Tokens (JWT). When a client is created it is assigned a key which is used for signing the JWT. The payload of the JWT should always contain the fields client
and magazine
.
These fields are used to identify the client making the request, and the magazine for which the request is intended. The payload will also contain additional fields, depending on the API of the specific service being used. The JWT token is then submitted to the Services API in the token
field of the JSON body of the request:
{
"token": "eyJhbGciOiJIUzI1NiJ9.eyJtYWdhemluZSI6Mjc3LCJjbGllbnQiOiJ0ZXN0LWNsaWVudCJ9.twNlYm_SSg9REr1yFUHNCxhezGJp1j-B4o9-DYp7xh8"
}
Please ask your Relevance contact person for the host of the Services API you should use.
Services
We will now describe the different services exposed by the Services API and how to use them.
Push
Endpoint: https://{services_api_host}/push
The Services API enables clients to send push notifications to platform users. The payload of the JWT token must contain the following additional fields:
- uids: An array containing the uid's of the users to which the push should be sent. These uid's must correspond to the uid's of the users on the Relevance platform.
- msg: A JSON object containing the following fields:
- message: The text of the message to be sent to the user.
- url: (Optional) A url to be passed to the app, for instance a universal link to an article or a plugin.
Here is an example of a complete payload for sending a push notification through the Services API:
{
"client": "test-client",
"magazine" : 305,
"uids": ["userID1", "userID2"],
"msg": {
"message": "This is the client speaking.",
"url": "https://orbit.ortec.com/a/1234"
}
}
Notifications
Endpoint: https://{services_api_host}/notifications
The Services API enables clients to submit custom notifications to the Relevance Notification Centre. These notifications will be displayed to the user in the Notification Centre, along with the other platform notifications.
The payload of the JWT must contain the following additional fields:
- uids: An array containing the uid's of the users to which the notification should be sent. These uid's must correspond to the uid's of the users on the Relevance platform.
- cdate: The creation date of the notification. This is set by the external system as there may be a delay between the time the notification was created and its submission to the Services API.
- title: The title that should be displayed to the user (optional).
- msg: The message that should be displayed to the user.
- link: The link that should be opened when the user selects the notification.
Here is an example of a complete payload for sending a notification through the Services API:
{
"client": "test-client",
"magazine" : 305,
"uids": ["userID1", "userID2"],
"title": "Notification",
"msg": "There is some news for you!",
"cdate": "2021-03-21T00:00:00Z",
"link": "https://www.somenewssite.com/news/article.html"
}