Part 3. Cloud API: Web Services APIs

Notification Endpoints

Click an ▶ API Endpoint to expand/collapse its content.
POST/notifications/:notification_type/devices/:device_id
Purpose: If there are any connection errors or information changes in the device, this API is invoked to send the notifications.
Request Method
POST
Changelog
Nov 10, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required notification_type String The type of the required notification, including: email, sms, and platform.
(The platform means sending push notifications from the Example service.)
Required device_id String The device_id of the device.
Required message String The cause of the error event. For example, connection error.
Return Values
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752
}
Unique Error Messages of this API
HTTP Status Code Error Message Description
400 INVALID_NOTIFICATION_TYPE The entered notification type does not exist.
400 INVALID_DEVICE_ID The device_id does not exist.
400 EMPTY_MESSAGE The cause of the error event is empty/null value.

▲ Top

POST/notifications/:notification_type/:datalandmark_id
Purpose: Once the DeviceMark is created, the notification will be sent.
Request Method
POST
Changelog
Nov 10, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify app_id and app_key of Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required notification_type String The type of the required notification, including: email, sms, and platform.
(The platform means sending push notifications from the Example service.)
Required datalandmark_id String The correspondent ID number of the DeviceMark.
Required account_id String The account_id of the user.
Required message String The cause of the error event.
Return Values
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752
}
Unique Error Messages of this API
HTTP Status Code Error Message Description
400 INVALID_NOTIFICATION_TYPE The entered notification type does not exist.
400 INVALID_DATALANDMARK_ID The datalandmark_id does not exist.
400 EMPTY_MESSAGE The cause of the error event is empty/null value.
400 INVALID_ACCOUNT_ID The account_id does not exist.

▲ Top

GET/notifications/accounts/:account_id
Purpose: Gets today’s unsent notification according to the account_id.
Request Method
GET
Changelog
Nov 10, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify app_id and app_key of Header belongs to the App to take further actions
Request Parameters
Need Parameter Type Description
Required account_id String The account_id of the user.
Return Values
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
notifications Array Get the list of the attribute.
Return Values in notifications array
Fields Type Description
notification_type String The types of the notification, including: email, sms, platform.
Notifications will be sent in different ways based on the types.
  • email: sent via email.
  • sms: sent via short message service.
  • platform: sent via APP Push-notification.
notification_message String The message of notification.
notification_from String The user’s email address or mobile phone number of the device which creates the notification.
notification_to Array The receiver of the notification.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "notifications": [{
    "notification_type": "sms",
    "notification_message": "send message from sms",
    "notification_from": "0912345678",
    "notification_to": [
      "0911223344",
      "0911223355"
    ]
 }]
}
Unique Error Messages of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The entered account_id does not exist.

▲ Top

GET/notifications
Purpose: Gets the list of the notifications and show the types of notification.
Request Method
GET
Changelog
Nov 10, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
None.
Return Values
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
notifications Array Get the list of the attributes.
Return Values in the notifications array
Fields Type Description
notification_id String The ID number of the Notification.
notification_name String The types of the notification, including: email, sms, platform.
Notifications will be sent in different ways based on the types.
  • Email: sent via Email.
  • SMS: sent via short message service.
  • Platform: sent via APP Push-notification.
    (The platform means sending push notifications from Example service.)
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "notifications": [{
    "notification_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "notification_name": "email"
  }]
}
Unique Error Messages of this API
None.

▲ Top

Notification flows

Notifications keep end users informed of events concerning devices and DeviceMarks.

  • The Example notification service provider is allowed to notify users through email, SMS text message, or push notification to the user app.
  • Notifications are sent to the selected end users by email or SMS about device and DeviceMark activities, such as an event detected by the device, and monitor changes in DeviceMarks.

▲ Top