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
For policy see Policies resources.
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.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
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.