Developer API Description

Overview

Full API documentation.

Version information

Version : 1.0

Contact information

Contact : Omnys Team
Contact Email : info@omnys.com

License information

License : Commercial License
License URL : http://www.omnys.com
Terms of service : http://www.omnys.com

URI scheme

Host : platform-rest:8080
BasePath : /

Tags

  • Alarms : Operations to retrieve data on alarms
  • Authentication : Authenticates a user
  • Commands : Operations to retrieve data on commands or send new ones
  • Firmware : Operations to retrieve and download firmware data
  • Measurements : Operations to retrieve measurements read from things
  • Things : Operations to retrieve data on things

Resources

Alarms

Operations to retrieve data on alarms

Fetch alarms within a given time range (results are paginated)

GET /api/v1/alarms
Parameters
Type Name Description Schema
Query end
required		 End date of the time range. integer (int64)
Query ids
optional		 Comma-separated list of resource ids belonging to the things the alarms are related to. If null/empty, retrieve all the alarms (regardless of the associated resource id). string
Query page
optional		 Results page you want to retrieve (0..N). string
Query size
optional		 Number of items per page. string
Query start
required		 Start date of the time range. integer (int64)
Responses
HTTP Code Description Schema
200 OK < AlarmView > array
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Authentication

Authenticates a user

Attempt to perform an authentication.

POST /auth
Parameters
Type Name Description Schema
Body Request
optional		 Credentials needed to login the system. AuthenticationRequest
Responses
HTTP Code Description Schema
200 OK object
201 Created No Content
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Commands

Operations to retrieve data on commands or send new ones

Fetch commands within a given time range (results are paginated)

GET /api/v1/commands
Parameters
Type Name Description Schema
Query end
required		 End date of the time range. integer (int64)
Query ids
optional		 Comma-separated list of resource ids belonging to the things the commands have been sent to (cannot be empty). string
Query page
optional		 Results page you want to retrieve (0..N). string
Query size
optional		 Number of items per page. string
Query start
required		 Start date of the time range. integer (int64)
Responses
HTTP Code Description Schema
200 OK < CommandView > array
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Send a command to a thing.

POST /api/v1/commands/{resourceId}
Parameters
Type Name Description Schema
Path resourceId
required		 Resource id of the thing which will receive the command. string
Body Command Data
required		 Data which makes up the command. topic is the suffix of the command topic. parValues is a parameter &rarr; value map which has to be used to fill in the parameters' placeholders. SendCommandInput
Responses
HTTP Code Description Schema
200 OK CommandView
201 Created No Content
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Firmware

Operations to retrieve and download firmware data

Fetch firmware for the organization of the currently logged in user (results are paginated)

GET /api/v1/firmware
Parameters
Type Name Description Schema
Query page
optional		 Firmware results page you want to retrieve (0..N). string
Query size
optional		 Number of firmware records per page. string
Query sort
optional		 Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported. < string > array(multi)
Responses
HTTP Code Description Schema
200 OK < FirmwareView > array
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Fetch firmware, given the related app id.

GET /api/v1/firmware/appId/{appId}
Parameters
Type Name Description Schema
Path appId
required		 Application id the firmware is used for. string
Responses
HTTP Code Description Schema
200 OK < FirmwareView > array
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Download firmware, given the related app id.

GET /api/v1/firmware/download/{appId}
Parameters
Type Name Description Schema
Path appId
required		 Application id the firmware is used for. string
Responses
HTTP Code Description Schema
200 OK No Content
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Measurements

Operations to retrieve measurements read from things

Return the last measurement recorded for a set of parameters

GET /api/v1/things/{resourceId}/measurements/last/parameters/{parameters}
Parameters
Type Name Description Schema
Path parameters
required		 The comma-separated list of parameters being requested. string
Path resourceId
required		 The resource id of the thing whose measurements are being requested. string
Query after
optional		 Start of the time range. integer (int64)
Query before
optional		 End of the time range. integer (int64)
Responses
HTTP Code Description Schema
200 OK < MeasurementView > array
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Return the measurements recorded for a thing parameter between a time range (results are paginated)

GET /api/v1/things/{resourceId}/measurements/{parameter}/timerange
Parameters
Type Name Description Schema
Path parameter
required		 The thing parameter for which get measurements. string
Path resourceId
required		 The resource id of the thing for which get measurements. string
Query end
optional		 The end moment in time (unix timestamp, millis from 1970). If not specified uses the current moment (now). integer (int64)
Query page
optional		 Results page you want to retrieve (0..N). string
Query size
optional		 Number of items per page. string
Query start
required		 The start moment in time (unix timestamp, millis from 1970). integer (int64)
Responses
HTTP Code Description Schema
200 OK < MeasurementView > array
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Things

Operations to retrieve data on things

Retrieve things' details, given a list of resource ids

GET /api/v1/things/multiple
Parameters
Type Name Description Schema
Query ids
required		 Comma-separated list of resource ids. string
Responses
HTTP Code Description Schema
200 OK < ThingView > array
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Generates a thing starting from an application id

PUT /api/v1/things/new/{applicationId}
Parameters
Type Name Description Schema
Path applicationId
required		 An application id. string
Body Thing Data
optional		 DTO which carries the data for generating a thing. ThingToGenerateUpdate
Responses
HTTP Code Description Schema
200 OK ThingView
201 Created No Content
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Run a filtered search (results are paginated)

POST /api/v1/things/search
Parameters
Type Name Description Schema
Body Filter Wrapper
optional		 Set of filters used during the search.
Allowed keys: clientid, family, name, network, resourceid, status.
Allowed operators: CONTAINS, ENDS_WITH, EQUAL, IN, STARTS_WITH.
Multiple keys in the same filter must be separated from \| to be combined in an "OR" fashion.		 ThingFilterRequestWrapper
Responses
HTTP Code Description Schema
200 OK < ThingView > array
201 Created No Content
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Retrieve the things' status, given a list of resource ids

GET /api/v1/things/status
Parameters
Type Name Description Schema
Query ids
required		 Comma-separated list of resource ids. string
Responses
HTTP Code Description Schema
200 OK < string, string > map
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content
Consumes
  • application/json
Produces
  • */*

Definitions

AlarmView

Name Schema
cause
optional		 string
code
optional		 string
id
optional		 string
name
optional		 string
resourceId
optional		 string
when
optional		 integer (int64)

AuthenticationRequest

Name Schema
password
optional		 string
username
optional		 string

CommandView

Name Schema
correlationId
optional		 string
id
optional		 string
isRequestReply
optional		 boolean
name
optional		 string
replyMessage
optional		 string
replyWhen
optional		 integer (int64)
requestMessage
optional		 string
requestWhen
optional		 integer (int64)
resourceId
optional		 string
userName
optional		 string

FirmwareView

Name Schema
applicationId
optional		 string
checksum
optional		 string
description
optional		 string
fileName
optional		 string
id
optional		 string

MeasurementView

Name Schema
resourceId
optional		 string
value
optional		 string
when
optional		 integer (int64)

SendCommandInput

Name Schema
parValues
optional		 < string, string > map
topic
optional		 string

ThingFilter

Name Schema
key
optional		 string
operator
optional		 string
value
optional		 string

ThingFilterRequestWrapper

Name Schema
filters
optional		 < ThingFilter > array
page
optional		 integer (int32)
size
optional		 integer (int32)
sort
optional		 string

ThingToGenerateUpdate

Name Schema
clientId
optional		 string
description
optional		 string
name
optional		 string
networkName
optional		 string
password
optional		 string
resourceId
optional		 string
userName
optional		 string

ThingView

Name Schema
applicationId
optional		 string
attributes
optional		 < string, string > map
clientId
optional		 string
creationDate
optional		 integer (int64)
description
optional		 string
id
optional		 string
name
optional		 string
resourceId
optional		 string
status
optional		 string