Things resources

An IoT developer can create, read, update and delete Things via the Bosch IoT Things HTTP API.

Model of Thing API version 2

{
  "thingId": "the.namespace:the-name",
  "policyId": "the.namespace:the-name",
  "definition": "namespace:model:version",
  "attributes": {
    "manufacturer": "ACME corp"
  },
  "features": {
    "featureId-0-to-n": {
      "properties": {
        "connected": true,
        "complexProperty": {
          "street": "my street",
          "house no": 42
        }
      }
    }
  }
}

Things root resource

The root resource contains information about which version is currently deployed.

 https://<host>/api/2/things

things-http-api-2-things.png

For policy see Policies resources.

Further notes

Note on thingId

note The Thing ID must start with a namespace prefix (Java package notation and a colon ‘:').
Due to the fact that a Thing ID often needs to be set in the path, we have restricted the set of allowed characters to those for Uniform Resource Identifiers (URI)
see http://www.ietf.org/rfc/rfc2396.txt.
For a POST request this restriction will apply automatically, as our service will generate the ID.
For a PUT request containing for example an $ character in the ID you will get the HTTP status code 400 with following message:

{
  "status": 400,
  "error": "thing.id.invalid",
  "message": "The ID '$1' is not valid! It did not match the pattern '(?<ns>|(?:(?:[a-zA-Z]\w*)(?:\.[a-zA-Z]\w*)*))\:(?:[-\w:@&=+,.!~*'_;]|%\p{XDigit}{2})(?:[-\w:@&=+,.!~*'$_;]|%\p{XDigit}{2})*'.",
  "description": "It must contain a namespace prefix (java package notation + a colon ':') + ID and must conform to RFC-2396 (URI) - check here if it does (select 'path' in the list): http://www.websitedev.de/temp/rfc2396-check.html.gz"
}

Note on featureId

Due to the fact that a Feature ID often needs to be set in the path of a HTTP request, we strongly recommend to use a restricted the set of characters (e.g. those for Uniform Resource Identifiers (URI) see http://www.ietf.org/rfc/rfc2396.txt ).

Note on attribute and property keys

We strongly recommend to use a restricted the set of characters for the keys (identifier) of Thing Attributes and Feature Properties. Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*.

Note on special fields

Apart of all fields of a Thing which can be set explicitly at Thing creation or modification, a Thing holds additional information which might be of interest.

  • _namespace
    The field value is the namespace encountered as a prefix of the Thing ID.
  • _created
    The field value represents the creation timestamp of the thing in ISO-8601 UTC format.
  • _modified
    The field value represent the latest modification of the Thing. The timestamp - in ISO-8601 UTC format - is set on each modification of a Thing.
  • _revision
    The field value represent how often the Thing was modified. This counter is incremented on each modification of a Thing.
  • _policy
    The field value represent the policy for the Thing. Find the concept at Policy.

Note on conditional requests

tip The Bosch IoT Things HTTP API supports Conditional Requests. Details are described in the Ditto HTTP API concepts.

Note on merge requests

The Bosch IoT Things HTTP API supports a very convenient way to update a thing and its parts when using the new PATCH method with payload of content type application/merge-patch+json. The Things service will merge the provided request body with the existing thing. This makes it possible to change only some parts of a thing in single request without providing the full thing structure in the request body.

Corporate information Data protection notice Legal information Support Free plans