# TMX Insight™ Service Platform 2.0 API Guide
The ThingsMatrix platform provides REST APIs that you can use to interact with the platform programmatically. The REST APIs are typically used when integrating the 3rd party apps or scripts. If you haven't used ThingsMatrix APIs before, make sure you read all charpters below.
# REST API Reference
# Authentication and Authorization
Authentication. The following authentication methods are supported for the REST APIs:
- API Key. Key can be generated and reset via GUI.
- Bearer Authentication. Bearer token can be generated via user login API. This API requires loginName and password (MD5).
Authorization is based on the user used in the authentication process when you call REST APIs.
# Using the REST APIs
The following topics describe how the REST APIs are structured and how you can interact with them.
# Pagination
Some APIs use pagination to limit the response size for resources that return a potentially large collection of items.
For example:
?page=1&size=100
A request to a paged API will result in a values array wrapped in a JSON object with some paging metadata. For example:
{
"totalElements": "integer (int32)",
"last": "boolean",
"totalPages": "integer (int32)",
"number": "integer (int32)",
"size": "integer (int32)"
}
# Ordering
Some resources support ordering by a specific field. This is provided by the sort query parameter.
Ordering can be ascending or descending. To specify the type of ordering, use the "asc" or "desc" for ascending or descending respectively. By default, ordering is descending.
For example:
?sort=name desc
?sort=property1,property2 asc
?sort=property1 asc&sort=property2 desc
?sort=attributes.location desc
# Filtering
Some resources support filtering by specific field values. This is provided by the query parameters.
For example:
?name=test
?name=test&attributes=location US
?attributes=location US,zipcode 12345&tags=tag1&page=1&size=10&sort=attributes.location desc'
# Responses
Most resources will return a response body in addition to the status code. Usually, the JSON schema of the entity returned is the following:
{
"code": "integer (int32)",
"data": "object",
"msg": "string"
}
Table of Return Code:
| Code | Description |
|---|---|
| -1 | unknown error |
| 0 | success |
| 9999 | fail |
| 10001 | request body check error %s |
| 10002 | %s service invocation failed |
| 10003 | duplicate record |
| 10004 | edit failed |
| 10005 | query failed |
| 10006 | delete failed |
| 10007 | %s non-existent |
| 10008 | %s %s do not match |
| 10009 | %s resource access failed |
| 10010 | %s cannot be empty |
| 10011 | %s isn't allowed to be edited |
| 10012 | %s isn't allowed to be deleted |
| 10013 | %s alreayd exists |
| 10014 | request body parse error |
| 10015 | unique field %s already exists |
| 10016 | %s ready only |
| 10017 | invalid id %s |
| 10018 | invalid sn %s |
| 10019 | table %s does not exist |
| 14101 | invalid token |
| 14102 | token parse failed |
| 14103 | not authorized |
| 14201 | username or password incorrect |
| 14202 | user forbidden |
| 14203 | company forbidden |
| 14401 | invalid or non-existent equipment |
| 14402 | "[%s/%s] relationship is not allowed to be modified |
| 14403 | "[%s] and device are related |
| 14404 | "[%s] model are inconsistent |
| 14405 | group does not have elements |
| 14406 | [%s] and group are related |
| 14407 | invalid operations (same group) |
| 14408 | no data available for %s-%s |
| 14410 | groupId:[%s] does not match model:[%s] |
| 14501 | the protocol does not support this instruction |
# Examples
The Section includes a few examples of requests for searching for devices, get device detail and more.
Example 1: List Devices
Request:
$ curl -X POST --header 'Content-Type: application/json' \
> --header 'Accept: application/json' \
> --header 'Authorization: Bearer <Token>' \
> -d '{ "compositeStatus": 1}' \
> 'https://demo.thingsmatrix.io/api/device/list'
Response:
{
"code":0,
"msg":"success",
"data":{
"content":[{
"id":"049f0fe6de9b764c",
"sn":"12345688922",
"imei":null,
"iccid":"234567890975",
"iccidOverwrite":1,
"sensorSn":"66180800800143",
"sensorOverwrite":1,
"onlineStatus":1,
"status":1,
"attributes":{},
"tags":[],
"description":null,
"creator":"admin",
"createTime":"2019-06-27 12:26:14",
"updator":null,
"updateTime":null,
"model":{
"id":"bf37ac4057e022a8",
"name":"TMA01",
"vendor":"ThingsMatrix",
"type":1,
"description":"Logistics Tracker (2G, LTE)",
"creator":"admin",
"createTime":"2019-06-25 03:55:27",
"updator":"",
"updateTime":null
},
"group":{
"id":"5c6e62336a837fdd",
"name":"tma01_g1",
"description":"",
"creator":"admin",
"createTime":"2019-06-25 04:15:58",
"updator":null,
"updateTime":null
}
},{
"id":"e7d8acd99ae7c7a6",
"sn":"12345688821",
...
},...,{
...
}],
"pageable":{
"sort":{
"sorted":true,
"unsorted":false
},
"offset":0,
"pageSize":15,
"pageNumber":0,
"paged":true,
"unpaged":false
},
"totalPages":5,
"totalElements":67,
"last":false,
"first":true,
"sort":{
"sorted":true,
"unsorted":false
},
"size":15,
"number":0,
"numberOfElements":15
}
}
Example 2: Query detail information of one device
Request:
$ curl -X GET --header 'Accept: application/json' \
> --header 'Authorization: Bearer <token>' \
> 'https://demo.thingsmatrix.io/api/device/sn/12345688922'
Response:
{
"code": 0,
"msg": "success",
"data": {
"id": "049f0fe6de9b764c",
"sn": "12345688922",
"imei": null,
"iccid": "234567890975",
"iccidOverwrite": 1,
"sensorSn": "66180800800143",
"sensorOverwrite": 1,
"onlineStatus": 1,
"status": 1,
"attributes": {},
"tags": [],
"description": null,
"creator": "admin",
"createTime": "2019-06-27 12:26:14",
"updator": null,
"updateTime": null,
"model": {
"id": "bf37ac4057e022a8",
"name": "TMA01",
"vendor": "ThingsMatrix",
"type": 1,
"description": "Logistics Tracker (2G, LTE)",
"creator": "admin",
"createTime": "2019-06-25 03:55:27",
"updator": "",
"updateTime": null
},
"group": {
"id": "5c6e62336a837fdd",
"name": "tma01_g1",
"description": "",
"creator": "admin",
"createTime": "2019-06-25 04:15:58",
"updator": null,
"updateTime": null
}
}
}