Nwave API provides special endpoints for device health monitoring. They allow building you to build your own monitoring system, device health dashboards, and or alerting systems.
The full API documentation is available at the end of the page.
...
Incident - something out of the ordinary happened with a device
Device state - the last or highest priority incident with additional information about device damaging/activation/positioning
Severity - level of importance. The higher it is the higher attention you have to pay to a device.
OK - there is no reason to worry about the devices
Info - detected a low-priority issue with a device, it can even be temporal
Warning - detected a high-priority problem, it can be possibly resolved by a customer itselfyourselves
Critical - detected a critical problem, the device preparing or need to be replaced
Error types - short description of an action that happened with the device and created an incident
Manual - someone has marked a device as damaged
Hardware Error - issue with device hardware (sensors, battery, radio, or Bluetooth module)
Last Message Time Error - no messages had been receiving at least for last 24
Anomalous Status Duration - temporarily disabled
Positioned But Inactive - a device is bound to a position, not damaged, but inactive
Positioned But Not Calibrated - the device is bound to a position, but Nwave Cloud has not received a notification about the device calibration
Incident reasons - a result of incident reason detection using the Nwave Replacement App and visual control.
Missing - a device has been lost from its position
Hidden Problem - a device is not fully functional or not functional at all, but visually it is ok
Not Confirmed - the detected problem is not confirmed
Not Specified - reason has not been specified, but the problem existing is confirmed
Broken Casing - a device body is broken
No Reason - the incident reason has not been investigated yet
Relation between error types and severity:
Severity | Error |
|---|---|
OK |
|
Info |
|
Warning |
|
Critical |
|
API
Before using this API you should create an Authorization Token. You can find instructions here: Generating Authorization Tokens
...
The endpoint responds with a list of devices with containing information about all incidents. New incidents are placed at the beginning of the list.
...
| Swagger open api macro | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||
openapi: 3.0.1
info:
title: Monitoring API
description: Device issues and health states
version: 1.3.1
servers:
- description: Production Server
url: https://api.nwave.io/monitoring/v1/
tags:
- name: incidents
description: API for device incidents
- name: devices
description: API for fetching device state with a list of open incidents
- name: schema
description: API for loading enum values
paths:
/incidents:
get:
tags:
- incidents
summary: Returns a list of open incidents
operationId: GetIncidents
security:
- ApiKeyAuth: []
parameters:
- name: device_id
in: query
required: false
description: 'Filter incidents by device id. Array supports a,b,c'
style: form
explode: false
schema:
type: array
items:
type: string
pattern: '^[0-9a-fA-F]+$'
- name: zone_id
in: query
required: false
description: 'Filter incidents by zone id. Array supports 1,2,3'
style: form
explode: false
schema:
type: array
items:
type: integer
format: int64
minimum: 0
- name: group_id
in: query
required: false
description: 'Filter incidents by group id. Array supports 1,2,3'
style: form
explode: false
schema:
type: array
items:
type: integer
format: int64
minimum: 0
- name: error_type
in: query
required: false
description: 'Filter incidents by error type enum. Array supports a,b,c'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/IncidentsTypesEnumModel'
- name: reason
in: query
required: false
description: 'Filter by reason enum. Array supports a,b,c'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/IncidentReasonEnum'
- name: created_time_from
in: query
required: false
description: 'Filter incidents older provided created time'
schema:
type: string
format: date-time
- name: created_time_to
in: query
required: false
description: 'Filter incidents earlier provided created time'
schema:
type: string
format: date-time
- name: resolved_time_from
in: query
required: false
description: 'Filter incidents older provided resolved time'
schema:
type: string
format: date-time
- name: resolved_time_to
in: query
required: false
description: 'Filter incidents earlier provided resolved time'
schema:
type: string
format: date-time
- name: is_resolved
in: query
required: false
description: 'Show resolved incidents'
schema:
type: boolean
- name: damaging
in: query
required: false
description: 'Show incidents that marked device as damaged'
schema:
type: boolean
- name: resolving_type
in: query
required: false
description: 'Filter incidents by resolving type enum'
schema:
enum:
- auto
- manual
title: Resolving_Type
type: string
- name: comment
in: query
required: false
description: 'Filter incidents by comment'
schema:
type: string
- name: damaged
in: query
required: false
description: 'Damaged Devices'
schema:
type: boolean
- name: active
in: query
required: false
description: 'Activated Devices'
schema:
type: boolean
- name: download
in: query
required: false
description: 'Download as CSV. Default false'
schema:
type: boolean
default: false
- name: level_id
in: query
required: false
description: 'Filter by group level id. Array supports 1,2,3'
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
- name: floor_number
in: query
required: false
description: 'Filter by group floor number'
schema:
type: integer
format: int32
- name: limit
in: query
required: false
description: 'Count of incidents in response'
schema:
type: integer
format: int64
default: 50
- name: offset
in: query
required: false
description: 'Offset of incidents in response'
schema:
type: integer
format: int64
default: 0
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseIncidentListBody'
description: OK
/devices/states:
get:
tags:
- devices
summary: Returns an actual states of devices
operationId: GetDevicesStatesV2
security:
- ApiKeyAuth: []
parameters:
- name: incident_type
in: query
required: false
description: 'Filter devices by error type. Array supports a,b,c'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/IncidentsTypesDeviceStateEnumModel'
- name: reason
in: query
required: false
description: 'Filter incidents by reason. Array supports a,b,c'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/IncidentReasonEnum'
- name: network_id
in: query
required: false
description: 'Filter devices by network_id. Array supports a,b,c'
style: form
explode: false
schema:
type: array
items:
format: uuid
type: string
- name: zone_id
in: query
required: false
description: 'Filter devices by zone id. Array supports 1,2,3'
style: form
explode: false
schema:
type: array
items:
type: integer
format: int64
- name: group_id
in: query
required: false
description: 'Filter devices by group id. Array supports 1,2,3'
style: form
explode: false
schema:
type: array
items:
type: integer
format: int64
- name: project_id
in: query
required: false
description: 'Filter devices by project id. Array supports 1,2,3'
style: form
explode: false
schema:
type: array
items:
type: integer
format: int64
- name: device_id
in: query
required: false
description: 'Filter devices by device_id. Array supports a,b,c'
style: form
explode: false
schema:
type: array
items:
type: string
pattern: '^[0-9a-fA-F]+$'
- name: severity
in: query
required: false
description: 'Filter device by severity level. Array supports a,b,c'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/DeviceStateSeverityEnumModel'
- name: damaged
in: query
required: false
description: 'Damaged Devices'
schema:
type: boolean
- name: active
in: query
required: false
description: 'Activated Devices'
schema:
type: boolean
- name: level_id
in: query
required: false
description: 'Filter by group level id. Array supports 1,2,3'
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
- name: floor_number
in: query
required: false
description: 'Filter by group floor number'
schema:
type: integer
format: int32
- name: limit
in: query
required: false
description: 'Count of incidents in response. Default last 100 items'
schema:
type: integer
format: int64
default: 100
- name: offset
in: query
required: false
description: 'Offset of incidents in response'
schema:
type: integer
format: int64
default: 0
- name: download
in: query
required: false
description: 'Download as CSV. Default false'
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseDeviceStatesListBody'
'202':
description: Downloadable file
content:
text/csv:
schema:
type: string
components:
schemas:
IncidentReasonEnum:
type: string
description: Incident reason classification
enum:
- missing
- hidden_problem
- not_confirmed
- not_specified
- broken_casing
- no_reason
IncidentState:
description: Incident states for different errors
properties:
error_datetime:
format: date-time
title: Error_Datetime
type: string
trace_id:
format: uuid
title: Trace_Id
type: string
required:
- error_datetime
title: IncidentState
type: object
Incident:
description: Datatype for incident
properties:
resolving_type:
enum:
- auto
- manual
title: Resolving_Type
type: string
comment:
title: Comment
type: string
created_time:
format: date-time
title: Created_Time
type: string
device_id:
title: Device_Id
type: string
error_type:
$ref: '#/components/schemas/IncidentsTypesEnumModel'
reason:
$ref: '#/components/schemas/IncidentReasonEnum'
id:
title: Id
type: integer
zone_id:
title: Zone_Id
type: integer
group_id:
title: Group_Id
type: integer
network_id:
format: uuid
title: Network_Id
type: string
damaged_status:
default: false
title: Damaged_Status
type: boolean
activation_status:
default: false
title: Activation_Status
type: boolean
is_resolved:
default: false
title: is_resolved
type: boolean
damaging:
default: false
title: damaging
type: boolean
resolved_time:
format: date-time
title: Resolved_Time
type: string
state:
$ref: '#/components/schemas/IncidentState'
user_id:
format: uuid
title: User_Id
type: string
required:
- device_id
- error_type
- state
- created_time
title: Incident
type: object
ResponseIncidentListBody:
description: Response with list of incidents
properties:
data:
items:
$ref: '#/components/schemas/Incident'
title: Data
type: array
message:
title: Message
type: string
total:
title: Total
type: integer
reason:
$ref: '#/components/schemas/ResponseReason'
title: ResponseIncidentListBody
type: object
DeviceStates:
title: DeviceStates
description: Device states
type: object
properties:
device_id:
title: Device_Id
type: string
zone_name:
title: Zone_Name
type: string
group_name:
title: Group_Name
type: string
zone_id:
title: Zone_Id
type: integer
group_id:
title: Group_Id
type: integer
project_name:
title: Project_Name
type: string
incident_type:
$ref: '#/components/schemas/IncidentsTypesDeviceStateEnumModel'
reason:
$ref: '#/components/schemas/IncidentReasonEnum'
incident_date:
title: Incident_Date
type: string
days_broken:
title: Days_Broken
type: integer
latitude:
title: Latitude
type: number
longitude:
title: Longitude
type: number
severity:
$ref: '#/components/schemas/DeviceStateSeverityEnumModel'
network_id:
format: uuid
type: string
required:
- device_id
IncidentsTypesEnumModel:
type: string
description: Types of Failures
enum:
- manual
- hardware_error
- last_message_time_error
- anomalous_status_duration
IncidentsTypesDeviceStateEnumModel:
type: string
description: Types of Failures
enum:
- manual
- hardware_error
- last_message_time_error
- anomalous_status_duration
- positioned_but_inactive
- positioned_but_not_calibrated
DeviceStateSeverityEnumModel:
type: string
description: Device state severity
enum:
- ok
- info
- warning
- critical
ResponseReason:
type: string
description: Responses reason
enum:
- ok
- created
- invalid_field
- no_data
- not_found
- not_implemented
- restricted
- server_error
ResponseDeviceStatesListBody:
description: Response with list of devices
properties:
data:
items:
$ref: '#/components/schemas/DeviceStates'
title: Data
type: array
message:
title: Message
type: string
total:
title: Total
type: integer
reason:
$ref: '#/components/schemas/ResponseReason'
title: ResponseDeviceStatesListBody
type: object
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Auth-Token |