Transport via HTTP

An aspect can have multiple endpoints assigned to allow for more complex interactions than just accessing the aspect data. Data retrieved from an endpoint must be encoded in JSON format, and aligned to the Aspect Model corresponding to the aspect endpoint as described in Payloadsexternallink 20.

The following table describes the possible options for HTTP endpoints:

{tenant-id} - Unique identifier of the owning tenant.
Table 1. HTTP Endpoint Types
Operation type Mandatory HTTP Verb DTR Type Path Description

Retrieve aspect data

GET

READ

/api/{api-version}/{tenant-id}/twins/{twin-id}/aspects/{aspect-id}

Retrieve available data of an aspect according to the related Aspect Model.

Filter aspect data

POST

FILTER

/query-api/{api-version}/{tenant-id}/twins/{twin-id}/aspects/{aspect-id}

Filter for specific information e.g., data between a defined time frame or to restrict the result to the desired information.
POST was chosen as the HTTP verb for this sort of operation as clients might want to apply very complex filters that exceed the technical limits of URL query parameters.

Execute aspect operation

(only if the Aspect Model defines operations)

POST

OPERATIONS

/rpc-api/{api-version}/{tenant-id}/twins/{twin-id}/aspects/{aspect-id}

Execute an operation according to JSON-RPC 2.0externallink 20 which is defined in the related Aspect Model.