Explore your XDK as a Thing

Use the Swagger UI to experience our REST-like HTTP API.

The entry point is apidocs.bosch-iot-suite.com

  1. API Version: 2
  2. Solution API Token: your API token.
    Book the Bosch IoT Things cloud service in case you don't have one yet.
    Please request a service plan as you will definitely need an identifier for each single API call.
    Tip: The API token is not bound to a user account, nor to the thing entity representing the XDK, but can be used for any application interaction with our API.
  3. Authorize:
    • At section OAuth2.0, use your Bosch-ID which you have used while registering the XDK.
    • Set your API Token - in case you didn't set it before.

Bosch IoT Things HTTP  API

  • Open the section GET /things/{thingId}
  • At thingId set the ID you find on the detail view when you click on the XDK in the My Things list. You also see this ID at the end of the first line of your config.txt file you used for the XDK registration.
  • Try it out!

A XDK which you have registered but not connected yet would look similar to following snippet:

{
  "thingId": "bosch.xdk:123-xxx-9",
  "policyId": "bosch.xdk:S-1-5-21-1937855695-xxx-xxx-5904",
  "features": {
    "description": {
      "properties": {
        "_definition": "com.bosch.iot.suite.standard.Descriptive:1.0.0",
        "displayName": "xdk-0101"
      }
    }
  }
}

Of course, as soon as your XDK is on, and sends its data to the cloud, the thing notation will show all XDK typical features and your sensor values.

{
  "features": {
    "IlluminanceSensor.0": {
      "properties": {
        "status": {
          "minMeasuredValue": 120960,
          "minRangeValue": 0,
          "units": "mlx",
          "maxMeasuredValue": 198720,
          "sensorValue": 195840,
          "maxRangeValue": 188000000
        }
      }
    },
    "description": {
      "properties": {
        "_definition": "com.bosch.iot.suite.standard.Descriptive:1.0.0",
        "displayName": "XDK-0101"
      }
    },
    "Gyroscope.0": {
      "properties": {
        "status": {
          "minRangeValue": -2000,
          "xValue": -2.928999900817871,
          "units": "Deg/s",
          "yValue": -3.0510001182556152,
          "zValue": 0.7319999933242798,
          "maxRangeValue": 2000
        }
      }
    },
    "Magnetometer.0": {
      "properties": {
        "status": {
          "minRangeValue": -2500,
          "compassDirection": 12.885527610778809,
          "xValue": 26,
          "units": "uT",
          "yValue": 5,
          "maxRangeValue": 2500,
          "zValue": 3
        }
      }
    },
    "LightControl.0": {
      "properties": {
        "configuration": {
          "onOff": false
        },
        "status": {
          "colour": "255,0,0"
        }
      }
    },
    "LightControl.1": {
      "properties": {
        "configuration": {
          "onOff": true
        },
        "status": {
          "colour": "255,165,0"
        }
      }
    },
    "HumiditySensor.0": {
      "properties": {
        "status": {
          "minMeasuredValue": 34,
          "minRangeValue": 0,
          "units": "%",
          "maxMeasuredValue": 39,
          "sensorValue": 38,
          "maxRangeValue": 100
        }
      }
    },
    "LightControl.2": {
      "properties": {
        "configuration": {
          "onOff": true
        },
        "status": {
          "colour": "255,255,0"
        }
      }
    },
    "Accelerometer.0": {
      "properties": {
        "status": {
          "minRangeValue": -2,
          "xValue": 0.01899999938905239,
          "units": "g",
          "yValue": 0.0010000000474974513,
          "zValue": 1.0089999437332153,
          "maxRangeValue": 2
        }
      }
    },
    "TemperatureSensor.0": {
      "properties": {
        "status": {
          "minMeasuredValue": 28.600000381469727,
          "minRangeValue": -40,
          "units": "Cel",
          "maxMeasuredValue": 32.459999084472656,
          "sensorValue": 28.600000381469727,
          "maxRangeValue": 85
        }
      }
    },
    "Barometer.0": {
      "properties": {
        "status": {
          "minMeasuredValue": 987.2100219726562,
          "minRangeValue": 300,
          "units": "hPa",
          "maxMeasuredValue": 988.1400146484375,
          "sensorValue": 987.75,
          "maxRangeValue": 1100
        }
      }
    },
    "AlertNotification.0": {
      "properties": {
        "status": {
          "alert": ""
        }
      }
    }
  }
}

Please note however, that Bosch IoT Things will not store historic data but only the latest value known. In order to track the sensor values you can subscribe to changes of your XDKs using the Things APIs (e.g. WebSocket API).

In case your scenario is based on a single sensor value, you can of course set filters within the request.

The following examples are related to the Illuminance Sensor, however the same pattern applies to all other features.

Request all values of the Illuminance Sensor

  • Select GET /things/{thingId}
  • Set the thingId: bosch.xdk:xxx
  • Set the fields: features/IlluminanceSensor.0
  • Try it out!

Tip: If you append it in the URL within a REST Client, the notation is slightly different as you will need
to use URL encoding for the : and the / characters.

https://things.s-apps.de1.bosch-iot-cloud.com/api/2/things/bosch.xdk%3Axxx?fields=features%2FIlluminanceSensor.0

Response body

{
  "features": {
    "IlluminanceSensor.0": {
      "properties": {
       "status": {
        "minMeasuredValue": 120960,
        "minRangeValue": 0,
        "units": "mlx",
        "maxMeasuredValue": 198720,
        "sensorValue": 195840,
        "maxRangeValue": 188000000
       }
      }
    }
  }
}

Request one property of the Illuminance Sensor only

Adjust the fields selector by describing the complete path, down to the value you are interested in:

features/IlluminanceSensor.0/properties/status/sensorValue

Response body

{
  "features": {
    "IlluminanceSensor.0": {
      "properties": {
        "status": {
          "sensorValue": 195840
        }
      }
    }
  }
}

Request the sensorValue of the Illuminance Sensor only

Given your App does not need the complete JSON object but only the value, you can use the Feature resources.

  • Select the Features section GET /things/{thingId}/features/{featureId}/properties/{propertyPath}
  • Set the thingId: bosch.xdk:xxx
  • Set the featureId: IlluminanceSensor.0
  • Set the propertyPath: status/sensorValue
  • Try it out!

Response body

195840