Skip to content

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:

1
2
3
  {
    "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.

Here is an example of a complete payload for sending a push notification through the Services API:

1
2
3
4
5
6
7
8
{
  "client": "test-client",
  "magazine" : 305,
  "uids": ["userID1", "userID2"],
  "msg": { 
    "message": "This is the client speaking."
  }
}