Messages

Messages informing about the implementation of certain changes during the execution of business logic can be sent not only to the platform but also to external services. HTTP requests in the API platform are used to organize the work on the messages, allowing the following operations:

1. Getting a list of messages.
2. Creating a new message.
3. Changing a message status.
4. Clearing a message list.
5. Unloading messages from history.
6. Unloading messages from history by interval.

Getting a list of messages

To receive a complete list of messages, you must send an  GET api/v1/messages request. It is important to keep in mind that if you don’t add additional restrictions on the number of downloaded messages, the response will receive exactly the same number of messages as specified for the given user account in the graphical interface. In this example, on the other hand, the boundaries of the start and end of message collection are specified in accordance with the rules for creating time boundaries (see the “HTTP REST API” section, the “General principles for generating requests” subsection, the “Working with lists” item).

Request

GET api/v1/messages?begin=1569438000000&end=1569468100000 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

[
    {
        "_id": "5d8c2eb3c79fe347384cf531",
        "type": "object",
        "time": 1569468083027,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    {
        "_id": "5d8bbaa4c82fdf001125a382",
        "type": "object",
        "time": 1569438372808,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    }
]

Creating a new message

In order to create a new message and send it to the platform from an external service, you must use the POST method. At the same time, the message body and all the fields necessary for configuration are indicated in the request body.

Request

POST /api/v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

BODY

Response

HTTP/1.1 200 OK

BODY

Changing a message status

In order to change the status of a message and mark it as read or, on the other hand, unread, you need to change the read field. For the read message, the value of its field is true, for unread – false.

It is worth noting that since the message received by the object cannot be considered as an entity, its identifier cannot be viewed in the “Edit” menu, which in turn is located in the “Administration” menu. Therefore, in order to know the identifier of the user’s message, it is recommended to upload a list of messages with all the necessary information at the beginning.

Request

PATCH /api/v1/messages/read/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

BODY

Response

HTTP/1.1 200 OK

BODY

Clearing a message list

To delete and clear all list of messages, should be sent DELETE /api/v1/messages/clear request.

Request

DELETE /api/v1/messages/clear HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

BODY

Unloading messages from history

As for objects, the system stores a message history that can be viewed by the user. When unloading the full list of messages from the history, an array of messages is returned in response to the request.

Request

GET /api/v1/messages/history HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

[
    {
        "_id": "5d8c2eb3c79fe347384cf531",
        "type": "object",
        "time": 1569468083027,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    {
        "_id": "5d8bbaa4c82fdf001125a382",
        "type": "object",
        "time": 1569438372808,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    {
        "_id": "5d8b11c2d0025e0012fd7100",
        "type": "object",
        "time": 1569395137986,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    }
]

Unloading messages from history by interval

In order to get only their number, the first and last message, instead of a complete list of messages, you need to send a request GET /api/v1/messages/history/bounds, the resource of which indicates a narrowing of the displayed information compared to the previous request.

Request

GET /api/v1/messages/history/bounds HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

{
    "count": 8,
    "min": {
        "_id": "5d8a6c965d60133726d3a478",
        "type": "object",
        "time": 1569352854108,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    "max": {
        "_id": "5d8c2eb3c79fe347384cf531",
        "type": "object",
        "time": 1569468083027,
        "id": "5a718f4543af42110079e8a4",
        "body": {
            "text": "It's too dark",
            "type": "text"
        },
        "importance": "information",
        "read": false
    },
    "success": true
}