Relations - deprecated

The HTTP Relations endpoint will be deprecated.
However, in case you still need to preserve some relation information, here are some alternatives:

  • For a simple parent-child-relation - you can use a parent property whithin the child thing instead.
  • For a source-target relation - use the things HTTP endpoint and store the information directy whithin a thing entity.
    The content could be for example the same as the things service has internally used in previouse versions:
      {
        "thingId": "my.namespace:relation-example-01",
        "attributes": {},
        "features": {
          "relation": {
            "properties": {
              "source": "my.namespace:ID-of-the-source-Thing",
              "target": "my.namespace:ID-of-the-target-Thing"
            }
          }
        }
      }
  • For more complex relationships use Topologies - BETA.
{
 "relationId": "string",
 "acl": {
   "authorizationSubject-1-to-n": {
     "READ": true,
     "WRITE": true,
     "ADMINISTRATE": true
   }
 },
 "source": "string",
 "target": "string",
 "attributes": {}
}

The root resource itself is the endpoint for relations.

https://<host>/api/1/relations

If you need a list of all Relations you are allowed to see please use the Search resource.

The operations available over the HTTP API are deprecated. Our Swagger UI does not support to try out these ressources, however in case you need the old API description, find the excerpt for relationa in the attached PDF file: 2018-10-bosch_iot_things-relations-http-api-deprecated-excerpt.pdf

Note on Relation ID

The Relation ID must start with a namespace prefix (Java package notation and a colon ':').
Due to the fact that a Relation 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 these restrictions 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 '$id' 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 Attribute Keys

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

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,