Features resources

A Feature is used to manage all data and functionality of a Thing that can be clustered in an outlined technical context.

Thing model

{
  "thingId": "the.namespace:theId",
  "policyId": "the.namespace:theId",
  "attributes": {},
  "features": {
    "featureId-0-to-n": {
      "definition": ["namespace:name:version", "optional:multiple:identifiers"],
      "properties": {
        "connected": true,
        "complexProperty": {
          "street": "my street",
          "house no": 42
        }
      },
      "desiredProperties": { 
         "connected": false
      }
    }
  }
}

Features resource

There is no root resource for features as they always belong to a Thing and do not exist without the Thing.
The sub-resources for Features start with

 https://<host>/api/2/things/{thingId}/features 

The following operations are available over the HTTP API:

Further notes

Note on thingId

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.thingId.invalid",
  "message": "Thing ID '$1' is not valid!",
  "description": "It 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",
  "href": null
}

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 desired properties

The features resources allow to create, read, update and delete desiredProperties along with the other properties.

Such desiredProperties fields can be used additionally or alternatively to other properties within get thing requests, search or count conditions, or filters.
Like for all other fields of a thing, the permission to read and write those fields is controlled via the policy.

Please note however, that besides persisting the desired properties, and indexing the fields for search requests, filtering etc. for the time being, the Bosch IoT Things service does not implement their further processing. Such functionality will come with future releases.

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.