ThingsMatrix Service Platform 2.4 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
    }
  }
}
Last updated: 3/26/2021, 9:27:55 AM