Fields and Field Masks

Field Masks

The Things Stack APIs use field masks to specify a subset of fields that should be returned by a reading request, or to specify fields that should be updated in a writing request. API request messages which contain a field_mask field operate this way - for example, GetEndDeviceRequest, or UpdateApplicationRequest, and most Get, List, Set, and Update requests. By default, these API requests will not return or update most fields, unless they are specified in a field mask.

The following fields are always returned:

  • Fields containing id
  • created_at
  • updated_at
  • deleted_at

All other fields are not returned and not updated, unless specified. Fields that are empty or zero are not returned, even if they are specified in a field mask.

Note:
For more information, see Google’s Protocol Buffers reference. Note that Google’s Protocol Buffers return all available fields if no field mask is specified, but The Things Stack API does not work this way, and no fields except the above mentioned are returned if no field mask is specified.

Fields and Field Masks in HTTP Queries

GET Requests

Fields may be specified in HTTP GET requests by appending them as query string parameters. For example, to request the name, description, and locations of devices in an EndDeviceRegistry.Get request, add these fields to the field_mask field. To get this data for device dev1 in application app1:

curl --location --header "Authorization: Bearer NNSXS.XXXXXXXXX" "https://thethings.example.com/api/v3/applications/app1/devices/dev1?field_mask=name,description,locations"

This will return the following:

Show JSON API response 
{
   "ids":{
      "device_id":"dev1",
      "application_ids":{
         "application_id":"app1"
      },
      "dev_eui":"46CF72F61862CBB0",
      "join_eui":"66209794D18AE087"
   },
   "created_at":"2020-07-31T12:17:51.645Z",
   "updated_at":"2021-07-20T14:14:56.318Z",
   "name":"device-name",
   "description":"device-description",
   "locations":{
      "user":{
         "latitude":52.51622086393074,
         "longitude":13.39075966780985,
         "source":"SOURCE_REGISTRY"
      }
   }
}

Without the field masks specified, this request would not return the name, description, and locations fields:

Show JSON API response 
{
   "ids":{
      "device_id":"ben-things-uno",
      "application_ids":{
         "application_id":"tti-playground"
      },
      "dev_eui":"46CF72F61862CBB0",
      "join_eui":"66209794D18AE087"
   },
   "created_at":"2020-07-31T12:17:51.645Z",
   "updated_at":"2020-07-31T12:17:51.645Z"
}

PUT Requests

PUT requests can be used to update entities by supplying the object as JSON data.

Note:

Keep in mind that application ID (application_ids.application_id), end device ID (device_id), AppEUI/JoinEUI (join_eui), DevEUI (dev_eui) and API key IDs cannot be updated after creation. These fields are part of the allowed field mask, but they can only be used at creation, after which they can no longer be changed.

For example, to properly register an end device in The Things Stack like described in the Using the API section, it is necessary to set the dev_eui field to device’s DevEUI. However, updating the DevEUI after device is created will not be possible, i.e. will fail with the forbidden path(s) in field mask error.

To update fields, the field mask must also be specified in the JSON object (query parameters do not work for PUT requests). The field mask has the following format:

{
  "field_mask": {
      "paths": [
        "ids.device_id",
        "name",
        "description"
      ]
    }
}

Where ids.device_id, name, and description are fields to be updated.

For example, to update the name field of device dev1 in application app1with an EndDeviceRegistry.Update request:

curl --location \
  --header 'Authorization: Bearer NNSXS.XXXXXXXXX' \
  --header 'Content-Type: application/json' \
  --request PUT \
  --data-raw '{
   "end_device":{
      "name":"device-name",
      "description":"device-description"
   },
    "field_mask": {
      "paths": [
        "name"
      ]
    }
  }' \
  'https://thethings.example.com/api/v3/applications/app1/devices/dev1'

This request will update the name field of the device, but will not update the description field because it is not specified in the field_mask object. The following will be returned as confirmation:

Show JSON API response 
{
   "ids":{
      "device_id":"dev1",
      "application_ids":{
         "application_id":"app1"
      },
      "dev_eui":"46CF72F61862CBB0",
      "join_eui":"66209794D18AE087"
   },
   "created_at":"2020-07-31T12:17:51.645Z",
   "updated_at":"2021-07-20T15:04:26.339Z",
   "name":"device-name"
}

To update both the name and description fields, the following request could be made:

curl --location \
  --header 'Authorization: Bearer NNSXS.XXXXXXXXX' \
  --header 'Content-Type: application/json' \
  --request PUT \
  --data-raw '{
   "end_device":{
      "name":"device-name",
      "description":"device-description"
   },
    "field_mask": {
      "paths": [
        "name",
        "description",
      ]
    }
  }' \
  'https://thethings.example.com/api/v3/applications/app1/devices/dev1'

This would return the following confirmation:

Show JSON API response 
{
   "ids":{
      "device_id":"dev1",
      "application_ids":{
         "application_id":"app1"
      },
      "dev_eui":"46CF72F61862CBB0",
      "join_eui":"66209794D18AE087"
   },
   "created_at":"2020-07-31T12:17:51.645Z",
   "updated_at":"2021-07-20T15:04:26.339Z",
   "name":"device-name",
   "description": "device-description",
}

POST Requests

Some endpoints require a message to be sent as part of the request. For example, to request an Event Stream, you must POST a StreamEventsRequest message:

curl --location \
  --header 'Authorization: Bearer NNSXS.XXXXXXXXX' \
  --header 'Content-Type: application/json' \
  --request POST \
  --data-raw '{
    "identifiers":[{
        "device_ids":{
            "device_id":"dev1",
            "application_ids":{"application_id":"app1"}
        }
    }]
  }' \
  'https://thethings.example.com/api/v3/events'
← Authentication Application APIs →