Notifications

API: Internal/Beta

Notifications help users stay up-to-date with events in UCloud.

Rationale

Powers the notification feature of UCloud. Other services can call this service to create a new notification for users. Notifications are automatically delivered to any connected frontend via websockets.

Table of Contents

1. Examples
Description
Creating a notification
Listening to notifications
List and Clear notifications
2. Remote Procedure Calls
Name Description
internalNotification Notifies an instance of this service that it should notify an end-user
list No description
subscription No description
create No description
createBulk No description
delete No description
markAllAsRead No description
markAsRead No description
3. Data Models
Name Description
CreateNotification No description
FindByNotificationIdBulk No description
Notification No description
InternalNotificationRequest No description
ListNotificationRequest No description
DeleteResponse No description
MarkResponse No description

Example: Creating a notification

Frequency of useCommon
Actors
  • The UCloud/Core service user (ucloud)
Communication Flow: Kotlin
NotificationDescriptions.create.call(
    CreateNotification(
        notification = Notification(
            id = null, 
            message = "Something has happened", 
            meta = JsonObject(mapOf("myParameter" to JsonLiteral(
                content = "42", 
                isString = false, 
            )),)), 
            read = false, 
            ts = 1662706353436, 
            type = "MY_NOTIFICATION_TYPE", 
        ), 
        user = "User#1234", 
    ),
    ucloud
).orThrow()

/*
FindByLongId(
    id = 56123, 
)
*/
Communication Flow: TypeScript
// Authenticated as ucloud
await callAPI(NotificationsApi.create(
    {
        "user": "User#1234",
        "notification": {
            "type": "MY_NOTIFICATION_TYPE",
            "message": "Something has happened",
            "id": null,
            "meta": {
                "myParameter": 42
            },
            "ts": 1662706353436,
            "read": false
        }
    }
);

/*
{
    "id": 56123
}
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as ucloud
curl -XPUT -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/notifications" -d '{
    "user": "User#1234",
    "notification": {
        "type": "MY_NOTIFICATION_TYPE",
        "message": "Something has happened",
        "id": null,
        "meta": {
            "myParameter": 42
        },
        "ts": 1662706353436,
        "read": false
    }
}'


# {
#     "id": 56123
# }
Communication Flow: Visual

Example: Listening to notifications

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
NotificationDescriptions.subscription.subscribe(
    Unit,
    user,
    handler = { /* will receive messages listed below */ }
)

/*
Notification(
    id = 56123, 
    message = "Something has happened", 
    meta = JsonObject(mapOf("myParameter" to JsonLiteral(
        content = "42", 
        isString = false, 
    )),)), 
    read = false, 
    ts = 1662706353437, 
    type = "MY_NOTIFICATION_TYPE", 
)
*/

NotificationDescriptions.markAsRead.call(
    FindByNotificationIdBulk(
        ids = "56123", 
    ),
    user
).orThrow()

/*
MarkResponse(
    failures = emptyList(), 
)
*/
Communication Flow: TypeScript
// Authenticated as user
await callAPI(NotificationsApi.markAsRead(
    {
        "ids": "56123"
    }
);

/*
{
    "failures": [
    ]
}
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/notifications/read" -d '{
    "ids": "56123"
}'


# {
#     "failures": [
#     ]
# }
Communication Flow: Visual

Example: List and Clear notifications

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
NotificationDescriptions.list.call(
    ListNotificationRequest(
        itemsPerPage = null, 
        page = null, 
        since = null, 
        type = null, 
    ),
    user
).orThrow()

/*
Page(
    items = listOf(Notification(
        id = 56123, 
        message = "Something has happened", 
        meta = JsonObject(mapOf("myParameter" to JsonLiteral(
            content = "42", 
            isString = false, 
        )),)), 
        read = false, 
        ts = 1662706353437, 
        type = "MY_NOTIFICATION_TYPE", 
    )), 
    itemsInTotal = 1, 
    itemsPerPage = 50, 
    pageNumber = 0, 
)
*/
NotificationDescriptions.markAllAsRead.call(
    Unit,
    user
).orThrow()

/*
Unit
*/
Communication Flow: TypeScript
// Authenticated as user
await callAPI(NotificationsApi.list(
    {
        "type": null,
        "since": null,
        "itemsPerPage": null,
        "page": null
    }
);

/*
{
    "itemsInTotal": 1,
    "itemsPerPage": 50,
    "pageNumber": 0,
    "items": [
        {
            "type": "MY_NOTIFICATION_TYPE",
            "message": "Something has happened",
            "id": 56123,
            "meta": {
                "myParameter": 42
            },
            "ts": 1662706353437,
            "read": false
        }
    ]
}
*/
await callAPI(NotificationsApi.markAllAsRead(
    {
    }
);

/*
{
}
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/notifications?" 

# {
#     "itemsInTotal": 1,
#     "itemsPerPage": 50,
#     "pageNumber": 0,
#     "items": [
#         {
#             "type": "MY_NOTIFICATION_TYPE",
#             "message": "Something has happened",
#             "id": 56123,
#             "meta": {
#                 "myParameter": 42
#             },
#             "ts": 1662706353437,
#             "read": false
#         }
#     ]
# }

curl -XPOST -H "Authorization: Bearer $accessToken" "$host/api/notifications/read/all" 

# {
# }
Communication Flow: Visual

Remote Procedure Calls

internalNotification

API: Internal/Beta Auth: Services

Notifies an instance of this service that it should notify an end-user

Request Response Error
InternalNotificationRequest Unit CommonErrorMessage

list

API: Internal/Beta Auth: Users

Request Response Error
ListNotificationRequest Page<Notification> CommonErrorMessage

subscription

API: Internal/Beta Auth: Users

Request Response Error
Unit Notification CommonErrorMessage

create

API: Internal/Beta Auth: Services

Request Response Error
CreateNotification FindByLongId CommonErrorMessage

createBulk

API: Internal/Beta Auth: Services

Request Response Error
BulkRequest<CreateNotification> BulkResponse<FindByLongId> CommonErrorMessage

delete

API: Internal/Beta Auth: Services

Request Response Error
FindByNotificationIdBulk DeleteResponse CommonErrorMessage

markAllAsRead

API: Internal/Beta Auth: Users

Request Response Error
Unit Unit CommonErrorMessage

markAsRead

API: Internal/Beta Auth: Users

Request Response Error
FindByNotificationIdBulk MarkResponse CommonErrorMessage

Data Models

CreateNotification

API: Internal/Beta

data class CreateNotification(
    val user: String,
    val notification: Notification,
)
Properties
user: String
notification: Notification

FindByNotificationIdBulk

API: Internal/Beta

data class FindByNotificationIdBulk(
    val ids: String,
)
Properties
ids: String

Notification

API: Internal/Beta

data class Notification(
    val type: String,
    val message: String,
    val id: Long?,
    val meta: JsonObject?,
    val ts: Long?,
    val read: Boolean?,
)
Properties
type: String
message: String
id: Long?
meta: JsonObject?
ts: Long?
read: Boolean?

InternalNotificationRequest

API: Internal/Beta

data class InternalNotificationRequest(
    val user: String,
    val notification: Notification,
)
Properties
user: String
notification: Notification

ListNotificationRequest

API: Internal/Beta

data class ListNotificationRequest(
    val type: String?,
    val since: Long?,
    val itemsPerPage: Int?,
    val page: Int?,
)
Properties
type: String?
since: Long?
itemsPerPage: Int?
page: Int?

DeleteResponse

API: Internal/Beta

data class DeleteResponse(
    val failures: List<Long>,
)
Properties
failures: List<Long>

MarkResponse

API: Internal/Beta

data class MarkResponse(
    val failures: List<Long>,
)
Properties
failures: List<Long>