v3.20.0

Getting Started Devices Gateways Integrations Reference
Get The Things Stack

Reference

    Overview
  • Adaptive Data Rate
  • API
    • Authentication
    • Fields and Field Masks
    • Application APIs
    • Application Package APIs
    • Application Pub/Sub APIs
    • Application Server APIs
    • Application Webhook APIs
    • Client APIs
    • End Device APIs
    • Events API
    • Gateway APIs
    • Gateway Server APIs
    • Gateway Server MQTT
    • Network Operations Center APIs
    • Network Server APIs
    • Organization APIs
    • Storage Integration API
    • Tenant APIs
    • User APIs
  • Application Packages
  • Billing with Stripe
  • Command-Line Interface
  • Components
  • Configuration
  • Data Formats
  • Data Retention and Privacy
  • Email Templates
  • Federated Authentication
  • Frequency Plans
  • FUOTA
  • Gateway RTT
  • Glossary
  • ID and EUI Constraints
  • Last Activity
  • LoRa Basics Station Implementation Guide
  • LoRaWAN Backend Interfaces Interoperability
  • LoRaWAN Specification and Regional Parameters
  • Networking
  • Packet Broker Routing
  • Packet Forwarders
  • Purging Entities
  • Rate Limiting
  • Resource Limiting
  • Root Certificates
  • Telemetry
  • Tenant Management
  • Web UI Branding

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. 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 →

On this page

  • Field Masks
  • Fields and Field Masks in HTTP Queries

The Things Stack

Getting Started

Devices

Gateways

Integrations

Reference

Contributing

GitHub

Forum

About Us

The Things Network

The Things Industries

About this page

Last changed by Krishna Iyer Easwaran on 05 Jan 2022.
Update EUI description for end device creation (#693)

Edit on Github