Device provisioning with special character in the ID

In this example, we assume the thing you create needs an empty space in its name, e.g. "org.example.namespace:thing-with-empty space"

Your entry point into our interactive API documentation is Bosch IoT Suite - Device Provisioning.

Table of contents

Example 1 - Provisioning request with empty space

  1. Authorize with a JWT (e.g. Create a Suite Auth client)

  2. Use the provisioning resource.
    POST /{service-instance-id}/devices

  3. Click Try it out to get all entry fields editable.

  4. Set the service-instance-id.
    If you have not stored your credentials at the end of the step Subscribe an Asset Communication package instance,
    open an new tab and navigate https://bosch-iot-suite.com/ > Service Subscriptions > your instance > ... Show Credentials
    copy the value of your Service Instance ID and switch back to the API docs to enter it in the respective field.

  5. Edit the content for the body.

  6. Set the request body.

    {
    "id": "org.example.namespace:thing-with-empty space",
    "hub": {
    "device": {
    "enabled": true
    },
    "credentials": {
    "type": "hashed-password",
    "secrets": [
    {
    "password": "yourPassword"
    }
    ]
    }
    },
    "things": {
    "thing": {
    "attributes": {
    "manufacturer": "Robert Bosch GmbH"
    }
    }
    }
    }
  7. Click Execute to submit the request.

  8. Verify that the request was successful Code 201.

You can download the result as JSON for further requests.

Example 1 - GET request with encoded empty space

  1. Authorization should still be valid (as the test token expires after 60 min)

  2. Use the Bosch IoT Things HTTP API v2.
    GET /things/{thingId}

  3. Click Try it out to get all entry fields editable.

  4. Set your ID the ids field to org.example.namespace:thing-with-empty space

    1. The original name used in the body part was "org.example.namespace:thing-with-empty space". At that point in time encoding was not necessary, as it was not part of the URL.

    2. The stored value in the Things persistence it indeed "org.example.namespace:thing-with-empty space" - as shown in the resulting JSON file

      However, if you have a look at the Curl section, you will see that the Swagger UI has encoded the empty space to %20 for you, resulting into

      org.example.namespace%3Athing-with-empty%20space

      If your application will request it, the encoding needs to be done within your application.

  5. Click Execute to submit the request.

  6. Upon success you will retrieve the complete thing with the given ID.

Example 2 - Provisioning with %

This example assume, your thing ID should be literally org.example.namespace:thing-with-%20

Given you set in the device provisioning request "id": "org.example.namespace:thing-with-%20"

When requesting it via culr GET /things/{thingId}, you need to encode the % character to %25.

This will be org.example.namespace:thing-with-%2520

curl -X GET "https://things.eu-1.bosch-iot-suite.com/api/2/things/org.example.namespace%3Athing-with-%2520" -H "accept: application/json"

Note on decoding and encoding of special characters

All APIs of the Bosch IoT Things service will expect encoding of input data and decoding of output data as required for the respective communication channel/protocol:

  • URL encoding for entities included in HTTP URLs (according to RFC 3986, i.e. %-escaping of most special characters)

  • HTTP conform delivery of HTTP header values (according to RFC 7230, Section 3.2.6)

  • JSON encoding in JSON content and Eclipse Ditto protocol message content (according to ECMA 404, The JSON Data Interchange Syntax, Chapter 9)

  • Respective encodings/decodings defined for AMQP/MQTT/Kafka (if needed according to the respective protocols)

No encoding/decoding is required when using Java with the Eclipse Ditto Java Client.