Skip to content

Notifications

The Notifications service has two functionalities:

On the one hand, it allows sending notifications to other services that are not directly connected to our service nor do we necessarily have to know who they are, this happens when, for example, a new offer is created, a request is sent to create a notification to service and notify the rest of services/marketplaces that have subscribed to that queue.

On the other hand, it is possible to create notifications for a certain user and store them, access the stored notifications, mark a notification as read, delete it, etc. To do this, follow the user notifications section.

Notifications to Services

Allows you to send notifications to other services that are not directly connected to our service and we do not necessarily know who they are. This happens when, for example, a new offer is created, a request is sent to create a notification to the service and notify the rest of the services/marketplaces that have subscribed to the queue.

This section can be understood from two points of view:

  • The first is that of a service that wishes to send a notification to others for a certain event.

  • The second is that of a service that expects to receive notifications to perform some action, such as indexing this event within the service.

For the first case we only need to follow the section Create Service Notification.

For the second case, we must follow the section Services and Queues in order to register our service within the Notification Manager and need to have an endpoint in our service to receive the notifications.

Services and Queues

In this section we explain the concepts of service and queue and indicate the methods to work with them.

A service is determined by a name, to identify our service within the system, a generic endpoint where to receive notifications and a list of queues to which it is subscribed.

A queue has a name that indicates what type of event it handles and it is possible to indicate a specific endpoint where it will send the notifications, this specific endpoint can be null and in that case it will use the generic endpoint of the service.

Types of queues

The following queues have been implemented within the Notification Manager:

  • offering.new
  • offering.update
  • agreement.accepted
  • agreement.rejected
  • agreement.update
  • agreement.pending
  • agreement.termination
  • agreement.claim

If it is determined that a queue is needed that does not currently exist, please contact me via email or open an issue in the project repository.

Service Management

Tip

All API methods have the prefix /api/v1 which will be omitted to make the endpoints clearer.

Tip

The Url of the service will be hidden in the examples and instead {NM} will be shown to indicate the address of the service.

This section provides methods to perform the following actions:

List all registered services

GET /services

Listing registered services

curl -X 'GET' \
  'http://{NM}/api/v1/services' \
  -H 'accept: application/json'
Response: 
[
  {
    "id": "4b83507c-3bd8-4ee5-a631-2841b7332e03",
    "name": "Agora Marketplace",
    "endpoint": "https://example.agora.com/api/i3mNotifications",
    "marketId": "marketA123"
    "queues": [
      {
        "id": "be6f938e-e44e-4a94-9d31-371083112fa4",
        "name": "offering.new",
        "endpoint": null,
        "active": true
      }
    ]
  },
  {
    "id": "322dcafa-5d30-48d7-9dc1-55c57fda0160",
    "name": "Test service",
    "endpoint": "https://webhook.site/8caaa1f8-ca85-40d6-a738-2cf42ba10243",
    "marketId": null
    "queues": [
      {
        "id": "d2fa4173-8d48-4a88-9b07-818cd68bf7df",
        "name": "offering.new",
        "endpoint": null,
        "active": true
      }
    ]
  }
]

Get the information of a service through its identifier

GET /services/{service_id}

Getting information from a particular service

curl -X 'GET' \
  'http://{NM}/api/v1/services/322dcafa-5d30-48d7-9dc1-55c57fda0160' \
  -H 'accept: application/json'
Response: 
{
  "id": "322dcafa-5d30-48d7-9dc1-55c57fda0160",
  "name": "Test service",
  "endpoint": "https://webhook.site/8caaa1f8-ca85-40d6-a738-2cf42ba10243",
  "queues": [
    {
      "id": "d2fa4173-8d48-4a88-9b07-818cd68bf7df",
      "name": "offering.new",
      "endpoint": null,
      "active": true
    }
  ],
  "marketId": null
}

Register a service

POST /services

Registering a new service

curl -X 'POST' \
  'http://{NM}/api/v1/services' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "service-test2",
  "endpoint": "https://webhook.site/d84c202f-f4c6-4251-9f77-74fbcea31d98"
}'

  • name: Name of the service to be registered, used to recognise the service.

  • marketId: Marketplace identifier, only necessary if we want to store this service as a marketplace so that it is possible to send requests only to this service, its value can be a string or null.

  • endpoint: Generic endpoint to receive the notifications in case we do not want to have a specific endpoint for each registered queue.

Response: 

{
  "id": "ef458948-c579-4ba7-b669-3383e7212f01",
  "name": "service-test2",
  "endpoint": "https://webhook.site/d84c202f-f4c6-4251-9f77-74fbcea31d98",
  "queues": [],
  "marketId": null
}

Once our service has been registered in the system, the next step would be to indicate to which queues we want to subscribe the service to receive notifications, , to do this follow the section register a queue.

Delete a service

DELETE /services/{service_id}

Deleting a service

curl -X 'DELETE' \
  'http://{NM}/api/v1/services/ef458948-c579-4ba7-b669-3383e7212f01' \
  -H 'accept: application/json'
Response: 
{
  "id": "ef458948-c579-4ba7-b669-3383e7212f01",
  "name": "service-test2",
  "endpoint": "https://webhook.site/d84c202f-f4c6-4251-9f77-74fbcea31d98",
  "queues": [],
  "marketId": null
}

Queue management

This section indicates the methods to carry out the following actions: * Register a queue * Get the service queues by identifier * Get the information of a specific queue by identifier * Activate-or-deactivate-a-queue * Delete a queue

Register a queue

Can also be called Subscribe service to queue.

POST /services/{service_id}/queues

Registering a queue to a service

curl -X 'POST' \
  'http://{NM}/api/v1/services/32f8fce0-34be-43cc-a13b-19300f39e296/queues' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "offering.new",
  "endpoint": null
}'

  • name: Name of the queue to which we want to subscribe our service.

  • endpoint: Specific endpoint to which we want to receive the notifications to this queue, it can be null.

Response: 

{
  "id": "83978171-c259-4670-8b3d-ff782a37e36c",
  "name": "offering.new",
  "endpoint": null,
  "active": true
}

Get the service queues by identifier

GET /services/{service_id}/queues

Getting the queues of a service

curl -X 'GET' \
  'http://{NM}/api/v1/services/32f8fce0-34be-43cc-a13b-19300f39e296/queues' \
  -H 'accept: application/json'
Response: 
[]

In this case the service is not subscribed to any queue, but the response in case it is subscribed to the offering.new queue would be as follows:

[
  {
    "id": "b11807ce-17ad-416f-9bd1-bdf9dd049dcf",
    "name": "offering.new",
    "endpoint": null,
    "active": false
  }
]
Obtain the information of a specific queue by identifier

GET /services/{service_id}/queues/{queue_id}

Getting a specific queue

curl -X 'GET' \
  'http://{NM}/api/v1/services/322dcafa-5d30-48d7-9dc1-55c57fda0160/queues/d2fa4173-8d48-4a88-9b07-818cd68bf7df' \
  -H 'accept: application/json'

Response: 

{
  "id": "d2fa4173-8d48-4a88-9b07-818cd68bf7df",
  "name": "offering.new",
  "endpoint": null,
  "active": true
}
Activate or deactivate a queue

PATCH /services/{service_id}/queues/{queue_id}/activate

PATCH /services/{service_id}/queues/{queue_id}/deactivate

Activating the subscription of a queue

curl -X 'PATCH' \
  'http://{NM}/api/v1/services/322dcafa-5d30-48d7-9dc1-55c57fda0160/queues/d2fa4173-8d48-4a88-9b07-818cd68bf7df/activate' \
  -H 'accept: application/json'

Activate Response: 

{
  "id": "d2fa4173-8d48-4a88-9b07-818cd68bf7df",
  "name": "offering.new",
  "endpoint": null,
  "active": true
}

Deactivating the subscription of a queue

curl -X 'PATCH' \
  'http://{NM}/api/v1/services/322dcafa-5d30-48d7-9dc1-55c57fda0160/queues/d2fa4173-8d48-4a88-9b07-818cd68bf7df/deactivate' \
  -H 'accept: application/json'

Deactivate Response: 

{
  "id": "d2fa4173-8d48-4a88-9b07-818cd68bf7df",
  "name": "offering.new",
  "endpoint": null,
  "active": false
}
Delete a queue

DELETE /services/{service_id}/queues/{queue_id}

Deleting a queue

curl -X 'DELETE' \
  'http://{NM}/api/v1/services/322dcafa-5d30-48d7-9dc1-55c57fda0160/queues/d2fa4173-8d48-4a88-9b07-818cd68bf7df' \
  -H 'accept: application/json'

Response:

{
  "id": "d2fa4173-8d48-4a88-9b07-818cd68bf7df",
  "name": "offering.new",
  "endpoint": null,
  "active": false
}

Create Service Notification

POST /notification/service

Create a service notification

curl -X 'POST' \
  'http://{NM}/api/v1/notification/service' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "receiver_id": "offering.new",
  "message": {"name":"this is a documentation test"}  
}'
* receiver_id: Name of the queue to which we want to send the message. * message: This message field is simply forwarded to the services subscribed to in the indicated queue.

Response: 

{}

The system will search among all the registered services, those that are subscribed to the queue indicated by the receiver_id, then it will create and send a notification to its registered endpoint.

Create Service Notification for a single Marketplace

POST /notification/service

Create a service notification for a single marketplace

curl -X 'POST' \
  'http://{NM}/api/v1/notification/service' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "receiver_id": "offering.new",
  "message": {"marketId":"market123",
    name":"this is a documentation test"}  

}'
* receiver_id: Name of the queue to which we want to send the message. * message: This message field is simply forwarded to the services subscribed to in the indicated queue.

Response: 

{}

The system will search among all the registered services, those that are subscribed to the queue indicated by the receiver_id, then it will create and send a notification to its registered endpoint.

Notifications to users

User notifications are messages that are created and stored to be read by the target users. The purpose of these messages is to notify users that an event relevant to them has occurred.

This section indicates the methods to perform the following actions:

Create user notifications

User notifications are created using a POST method.

POST /notification

Create a User Notification

curl -X POST "http://{NM}/api/v1/notification" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \ 
  -d '{
      "origin": "i3m", 
      "predefined": true, 
      "type": "offering.new", 
      "receiver_id": "UserID123", 
      "message": {
          "name":"This is a notification test"
      },
      "status": "Ok"
  }'
  • origin: Identifier of the user or service to whom the notification comes from.
  • predefined: This field must always be true.
  • type: queue_type of the notification
  • receiver_id: Destination of the notification
  • message: This field will contain the message that will be sent to the user by means of a forwarding, so no checks are made on the data sent.
  • status: Status of the notification

Response: 

{
  "id": "323e4e84-cef7-439a-9ad9-8324fef73792",
  "action": "offering.new",
  "status": "Ok",
  "origin": "i3m",
  "receptor": "UserID123",
  "unread": true,
  "data": {
    "name": "This is a notification test"
  },
  "dateCreated": "2022/06/14T10:38:38Z"
}

Access to notifications

Once a user notification has been created, it can be accessed using one of the following access methods.

Access all stored notifications

GET /notification

This method allows access to all notifications stored in the system, including their identifiers and the information contained within the message field.

Getting all stored notifications

curl -X 'GET' \
  'http://{NM}/api/v1/notification' \
  -H 'accept: application/json'

Response: 

[
    {
      "id": "60dd4714-899f-4dbe-8578-f1f39b6dbac2",
      "action": "agreement.accepted",
      "status": "accepted",
      "origin": "scm",
      "receptor": "consumer_333",
      "unread": true,
      "data": {
        "msg": "Agreement signed"
      },
      "dateCreated": "2022/06/14T10:38:38Z"
    },
    {
      "id": "807e48d8-112f-4c37-9b67-ef3ce76bf7d4",
      "action": "agreement.accepted",
      "status": "accepted",
      "origin": "scm",
      "receptor": "Siemens",
      "unread": true,
      "data": {
        "msg": "Agreement signed"
      },
      "dateCreated": "2022/06/14T10:38:38Z"
    },
    {
      "id": "323e4e84-cef7-439a-9ad9-8324fef73792",
      "action": "offering.new",
      "status": "Ok",
      "origin": "i3m",
      "receptor": "UserID123",
      "unread": true,
      "data": {
        "name": "This is a notification test"
      },
      "dateCreated": "2022/06/14T10:38:38Z"
    }
]

Get all unread notifications

GET /notification/unread

Get all users unread notifications

curl -X 'GET' \
'http://{NM}/api/v1/notification/unread' \
-H 'accept: application/json'

Response: 

[
    {
        "id": "60dd4714-899f-4dbe-8578-f1f39b6dbac2",
        "action": "agreement.accepted",
        "status": "accepted",
        "origin": "scm",
        "receptor": "consumer_333",
        "unread": true,
        "data": {
          "msg": "Agreement signed"
        },
        "dateCreated": "2022/06/14T10:38:38Z"
    },
    {
        "id": "807e48d8-112f-4c37-9b67-ef3ce76bf7d4",
        "action": "agreement.accepted",
        "status": "accepted",
        "origin": "scm",
        "receptor": "Siemens",
        "unread": true,
        "data": {
          "msg": "Agreement signed"
        },
        "dateCreated": "2022/06/14T10:38:38Z"
    },
    {
        "id": "323e4e84-cef7-439a-9ad9-8324fef73792",
        "action": "offering.new",
        "status": "Ok",
        "origin": "i3m",
        "receptor": "UserID123",
        "unread": true,
        "data": {
          "name": "This is a notification test"
        },
        "dateCreated": "2022/06/14T10:38:38Z"
    }
]

Get notifications by user ID

GET /notification/user/{user_id}

Get the notifications of a user

curl -X 'GET' \
  'http://{NM}/api/v1/notification/user/UserID345' \
  -H 'accept: application/json'

Response: 

[
  {
    "id": "b8e3c396-3fb5-4a6d-af6f-04b9cd44996f",
    "action": "offering.new",
    "status": "Pending",
    "origin": "i3m",
    "receptor": "UserID345",
    "unread": true,
    "data": {
      "name": "this is a test2"
    },
    "dateCreated": "2022/06/14T10:38:38Z"
  },
  {
    "id": "7da83c5f-3b71-4273-be23-b24bc91d4326",
    "action": "offering.new",
    "status": "Pending",
    "origin": "i3m",
    "receptor": "UserID345",
    "unread": false,
    "data": {
      "name": "this is a test1"
    },
    "dateCreated": "2022/06/14T10:38:38Z"
  }
]

Get all unread notifications from a user

GET /notification/user/{user_id}/unread

Get an unread user notification

curl -X 'GET' \
  'http://{NM}/api/v1/notification/user/UserID345/unread' \
  -H 'accept: application/json'

Response:

[
  {
    "id": "b8e3c396-3fb5-4a6d-af6f-04b9cd44996f",
    "action": "offering.new",
    "status": "Pending",
    "origin": "i3m",
    "receptor": "UserID345",
    "unread": true,
    "data": {
      "name": "this is a test2"
    },
    "dateCreated": "2022/06/14T10:38:38Z"
  }
]

Get notification by Notification ID

GET /notification/{notification_id}

Get a notification by ID

curl -X 'GET' \
  'http://{NM}/api/v1/notification/b8e3c396-3fb5-4a6d-af6f-04b9cd44996f' \
  -H 'accept: application/json'

Response: 

{
  "id": "b8e3c396-3fb5-4a6d-af6f-04b9cd44996f",
  "action": "offering.new",
  "status": "Pending",
  "origin": "i3m",
  "receptor": "UserID345",
  "unread": true,
  "data": {
    "name": "this is a test2"
  },
  "dateCreated": "2022/06/14T10:38:38Z"
}

Modification of the notifications

The following methods are used to make changes to notifications, such as marking them as read/unread and deleting notifications.

Mark notification as read

PATCH /notification/{notification_id}/read

Mark notification as read

curl -X 'PATCH' \
  'http://{NM}/api/v1/notification/b8e3c396-3fb5-4a6d-af6f-04b9cd44996f/read' \
  -H 'accept: application/json'

Response: 

{
  "id": "b8e3c396-3fb5-4a6d-af6f-04b9cd44996f",
  "action": "offering.new",
  "status": "Pending",
  "origin": "i3m",
  "receptor": "UserID345",
  "unread": false,
  "data": {
    "name": "this is a test2"
  },
  "dateCreated": "2022/06/14T10:38:38Z"
}

Mark notification as unread

PATCH /notification/{notification_id}/unread

Mark notification as unread

curl -X 'PATCH' \
  'http://{NM}/api/v1/notification/b8e3c396-3fb5-4a6d-af6f-04b9cd44996f/unread' \
  -H 'accept: application/json'

Response: 

{
  "id": "b8e3c396-3fb5-4a6d-af6f-04b9cd44996f",
  "action": "offering.new",
  "status": "Pending",
  "origin": "i3m",
  "receptor": "UserID345",
  "unread": true,
  "data": {
    "name": "this is a test2"
  },
  "dateCreated": "2022/06/14T10:38:38Z"
}

Delete notifications

The following method is used to delete a notification

DELETE /notification/{notification_id}

Deleting a notification

curl -X 'DELETE' \
  'http://{NM}/api/v1/notification/b8e3c396-3fb5-4a6d-af6f-04b9cd44996f' \
  -H 'accept: application/json'

Response: 

{
  "id": "b8e3c396-3fb5-4a6d-af6f-04b9cd44996f",
  "action": "offering.new",
  "status": "Pending",
  "origin": "i3m",
  "receptor": "UserID345",
  "unread": true,
  "data": {
    "name": "this is a test2"
  },
  "dateCreated": "2022/06/14T10:38:38Z"
}

Last update: 2022-07-22
Created: 2022-04-06
Back to top