Mappings
Every interface must have an array of mappings. Mappings are designed around REST controller semantics: each mapping describes an endpoint which is resolved to a path, it is strongly typed, and can have additional options. Just like in REST controllers, Endpoints can be parametrized to build REST-like collection and trees. Parameters are identified by %{parameterName}, with each endpoint supporting any number of parameters.
This is how a parametrized mapping looks like:
[...]
"mappings": [
{
"endpoint": "/%{itemIndex}/value",
"type": "integer",
"reliability": "unique",
"retention": "discard"
},
[...]
In this example, /0/value, /1/value or /test/value all map to a valid endpoint, while /te/st/value can't be resolved by any endpoint.
Supported Data Types
The following types are supported:
double: A double-precision floating-point number as specified by binary64, by the IEEE 754 standard (NaNs and other non numerical values are not supported).integer: A signed 32 bit integer.boolean: Eithertrueorfalse, adhering to JSON boolean type.longinteger: A signed 64 bit integer (please note thatlongintegeris represented as a string by default in JSON-based APIs.).string: An UTF-8 string, at most 65536 bytes long.binaryblob: An arbitrary sequence of any byte that should be shorter than 64 KiB. (binaryblobis represented as a base64 string by default in JSON-based APIs.).datetime: A UTC timestamp, internally represented as milliseconds since 1st Jan 1970 using a signed 64 bits integer. (datetimeis represented as an ISO 8601 string by default in JSON based APIs.)doublearray,integerarray,booleanarray,longintegerarray,stringarray,binaryblobarray,datetimearray: A list of values, represented as a JSON Array. Arrays can have up to 1024 items and each item must respect the limits of its scalar type (i.e. each string in astringarraymust be at most 65536 bytes long, each binary blob in abinaryblobarraymust be shorter than 64 KiB).
Make sure that the differences between two distinct interface names are not limited to the casing or the presence of hyphens. This situation leads to a collision in the interface names which brings to an error in the interface installation process.
Limitations
A valid interface must resolve a path univocally to a single endpoint. Take the following example:
[...]
"mappings": [
{
"endpoint": "/%{itemIndex}/value",
"type": "integer"
},
{
"endpoint": "/myPath/value",
"type": "integer"
},
[...]
In such a case, the interface isn't valid and is rejected, due to the fact that path /myPath/value is ambiguous and could be resolved to two different endpoints.
Any endpoint configuration must not generate paths that are prefix of other paths, for this reason the following example is also invalid:
[...]
"mappings": [
{
"endpoint": "/some/thing",
"type":"integer"
},
{
"endpoint": "/some/%{param}/value",
"type": "integer"
},
[...]
In case the interface's aggregation is object, additional restrictions apply. Endpoints in the same interface must all have the same depth, and the same number of parameters. If the interface is parametrized, every endpoint must have the same parameter name at the same level. This is an example of a valid aggregated interface mapping:
[...]
"mappings": [
{
"endpoint": "/%{itemIndex}/value",
"type": "integer"
},
{
"endpoint": "/%{itemIndex}/otherValue",
"type": "string"
},
[...]
Additional limitations (which stem from the MQTT protocol specification) can be outlined. When using parametric endpoints, the actual values used in place of parameter placeholders must fulfill the following requirements:
- endpoint parameters must be non-empty UTF-8 encoded strings;
- endpoint parameters must not contain the following characters:
+and#. Those characters are treated as wildcards for MQTT topics and therefore must be avoided; - endpoint parameters must not contain the
/character.