Operations Hub REST APIs for Integration

In addition to the existing APIs that allow devices to send data to the M2M_data entity, Operations Hub provides REST Integration APIs that enable 3rd party servers to pull data from the M2M_data entity. There are also APIs for pulling data from any custom entity in the Operations Hub database and for inserting data into custom entities.

Authentication

Before using the integration APIs, the client system must pass authentication on the Operations Hub server. The integration API login URL is https://<Operations Hub_Site_URL>/app/iqp/api/rest/login.

Message sent by the client: {"username":"<user>","password":"<pass>"}

Response of the server:

If authentication succeeds, the server responds with code 1 and provides a token for the client to use in further communications: {"code" : "1" , "token" : "<token>"}
If authentication fails, the server responds with code 0 and provides a reason for the failure: {"code" : "0" , "reason" : "<reason>"}. If the authentication fails, the client will need to request for authentication again before proceeding.

Get M2M data

The Get M2M data API allows a 3rd party server to retrieve data from the Operations Hub M2M_data entity: The URL for the API is: https://<Operations Hub_Site_URL>/app/iqp/api/rest/iot/data

Message sent by the client:

{"token": "<token>", "filters":
                [
                {"filter_type":"<column_name>","value":"<search_value>","value_type":"<type>","operator":"<operator>"}
                    ]
                    }

“<token>”: The token provided to the client at login.
“<column _name>”: The name of a valid field in the M2M_data entity.
“<search_value>”: The value to search for in the selected field.
“<type>”: The data type of the selected field. The following values are supported:
- Boolean
- Number
- Real
- String
- Long string
- Free text
- Date
- Time
- DateTime
- File
“<operator>”: The operator to use in the search. The following values are supported:
- =
- >
- <
- >=
- <=
- <>
- LIKE

Tip: If required, multiple filters can be provided to filter the search results. All filters are treated as {filter_1} AND {filter_2} AND … {filter_n}.

An example of a request to retrieve all M2M_data for the device “REST_Device” after 12:00pm on 2015-03-19:

{"token":"08ad9058-9ec9-4363-85f1-c9071004d9992","filters":
                    [
                    {"filter_type":"device_id","value":"REST_Device","value_type":"String","operator":"="},
                    {"filter_type":"iqp_timestamp","value":"2015-03-19T12:00:00.000Z","value_type":"DateTime","operator":">"}
                    ]
                    }

Response of the server:

If there is data to match the search results, the server will respond with all of the matching rows in the following format:

{"rows":
                        [
                        {"row":[<list of  <column_name>:<value>  pairs for all M2M_data columns>]},
                            {"row":[<list of <column_name>:<value>  pairs for all M2M_data columns>]},
                                ….
                                ]
                                }

If there is no data to match the search results, the server will respond with an empty list:
```
{"rows":[]}
```

Get Entity data

The Get Entity data API allows a 3rd party server to retrieve data from any custom entity in the Operations Hub database: The URL for the API is https://<Operations Hub_Site_URL>/app/iqp/api/rest/DB/data/get.

Message sent by the client:

{"token": "<token>", "entity_name":"<entity_name>", "filters":
                    [
                    {"filter_type":"<column_name>","value":"<search value>","value_type":"<type>","operator":"<operator>"}
                        ]
                        }

“<token>”: The token provided to the client at login.
“<entity_name>”: The name of a valid custom entity.
“<column _name>”: The name of a valid field in the specified entity.
“<search_value>”: The value to search for in the selected field.
“<type>”: The data type of the selected field. The following values are supported:
- Boolean
- Number
- Real
- String
- Long string
- Free text
- Date
- Time
- DateTime
- File
“<operator>”: The operator to use in the search. The following values are supported:
- =
- >
- <
- >=
- <=
- <>
- LIKE

Tip: If required, multiple filters can be provided to filter the search results. All filters are treated as {filter_1} AND {filter_2} AND … {filter_n}.

An example of a request to retrieve all data from the custom entity “MathsData”, where the value in the column “Angle” is between “180” and “270” degrees:

{“token”:”5aad6209-bd6f-440c-9581-26ea80ec6fd32”,”entity_name”:”MathsData”,”filters”:
                [
                {“filter_type”:”Angle”,”value”:”180”,”value_type”:”number”,”operator”:”>=”},
                {“filter_type”:”Angle”,”value”:”270”,”value_type”:”number”,”operator”:”<=”}
                ]
                }

An example of a request to retrieve all rows of data from the custom entity “MathsData” with no conditions:

{“token”:”5aad6209-bd6f-440c-9581-26ea80ec6fd32”,”entity_name”:”MathsData”,”filters”:[]}

Response of the server:

If there is data to match the search, the server will respond with all of the matching rows in the following format:

{"entity_name":"<entity_name>","rows":
                        [
                        {"row":
                        [
                        {"col_name":"<column_name>","type":"<column_type>","value":"<value>"},
                            {"col_name":"<column_name>","type":"<column_type>","value":"<value>"},
                                ….
                                ]
                                }
                                ….
                                ]
                                }

“<entity_name>”: The name of the entity the data was retrieved from.
“<column _name>”: The name of the field this value is from.
“<column_type>”: The data type of the field as specified in the entity.
“<value>”: The value of the field.

If there is no data to match the search, the server will respond with a blank list: {"entity_name":"<entity_name>","rows":[]}

Insert Entity data

The Insert Entity data API allows a 3rd party server to insert data into any custom entity in the Operations Hub database: The URL for the API is https://<Operations Hub_Site_URL>/app/iqp/api/rest/DB/data/insert.

Message sent by the client:

{"token": "<token>","entity_name":"<entity_name>","rows":
                    [
                    {"row":
                    [
                    {"col_name":",column_name>","type":"<type>","value":"<value>"},
                        {"col_name":"<column_name>","type":"<type>","value":"<value>"},
                            ….
                            ]
                            }
                            ….
                            ]
                            }

“<token>”: The token provided to the client at login.
“<entity_name>”: The name of the custom entity that you want to insert data into.
“<column _name>”: The name of the field in the specified custom entity that this value will be inserted into.
“<type>”: The data type of the specified field. The following values are supported:
- Boolean
- Number
- Real
- String
- Long string
- Free text
- Date
- Time
- DateTime
- File
Note: The type specified in the API call must be the same as the type specified for the field in the entity.
“<value>”: The value to insert into the field.

An example of a message to insert 2 rows of data into the custom entity “MathsData”:

{"token":"9eb64909-3d08-43e8-b5ed-eae57bce32402","entity_name":"MathsData","rows":
                [
                {"row":
                [
                {"col_name":"Angle","type":"number","value":"370"},
                {"col_name":"SIN","type":"real","value":"0.1736"},
                {"col_name":"COS","type":"real","value":"0.9848"},
                {"col_name":"TAN","type":"real","value":"0.1763"}
                ]
                },
                {"row":
                [
                {"col_name":"Angle","type":"number","value":"380"},
                {"col_name":"SIN","type":"real","value":"0.342"},
                {"col_name":"COS","type":"real","value":"0.9397"},
                {"col_name":"TAN","type":"real","value":"0.364"}
                ]
                }
                ]
                }

Response of the server:

If the insert is successful, the server will respond with code 1: {"code" : "1"}
If the insert fails, the server will respond with code 0 and a reason: {"code" : "0", "reason" : "<reason>"}