It is possible to access IoTEntity properties via a RESTful API. The REST interface provides a data-oriented interface for the IoTEntity that enhances usability for some types of clients including end-user browser access.
Access to the latest status and other property values of an IoTEntity is provided using GET request method over HTTP. Similarly, new entities, properties and state observation values can be added using the POST request method. The PUT request method is used for setting property values, and is thus an enabler for control actions. For these update functions see Updating IoTEntity Data REST.
Object identification – the URI structure
The URI structure for identification of resources follows the model described in IoTEntity – Content Model. The full URI template use a combination of collection names and instance identifiers in the following way:
{base}/IoTEntities/{IoTEntityID}/properties/{IoTPropertyID}/observations
“IoTEntities”, “properties” and “observations” denotes collections on the respective levels. Explicitly naming collections and types in the URI is helpful to make the semantics of the service clear to both developers and users.
Retrieving data – The GET request method
The GET method will, depending on if the URI identifies a collection or a resource, retrieve all resources in a collection or a single resource. The URI can be cut on all levels, enabling addressing components and collections on all levels. The full URI as expressed above used in a GET request would return a collection of IoTStateObservation elements for the property “IoTPropertyID” within the “IoTEntityID” entity. The following shortened URI would accordingly return a collection of all properties for the “IoTEntityID” entity:
{base}/IoTEntities/{IoTEntityID}/properties
Below is a complete list of what is returned when the corresponding URI is used in a GET request:
{base}/IoTEntities
Returns a collection of all IoTEntities within the scope of the {base}. These will be wrapped in the parent element ArrayOfIoTEntity.
The collection supports filters based on query string parameters in the following way:
?take=x : include up to x IoTEntities in the collection. Not supplying this parameter may result in an implicit limit set by the interface implementation (e.g. 500 elements) to enhance responsiveness.
?skip=x : given the other filter parameters and ordering, skip the first x elements in the collection. The parameter take will be applied to the subsequent elements.
?after=x : all elements after this xsd:dateTime. In the case of IoTEntity, this applies to creation date.
?before=x : all elements beforethis xsd:dateTime. In the case of IoTEntity, this applies to creation date.
?like=x : include all IoTEntities with the substring ‘x’ in the @about value (the identifier of the IoTEntity) or in the Name element. x is a regular expression which will be evaluated with the case-insensitive flag set.
{base}/IoTEntities/{IoTEntityID}
Returns the IoTEntity identified by {IoTEntityId}. The @about attribute will be equal to {IoTEntityId}.
{base}/IoTEntities/{IoTEntityID}/properties
Returns a collection of all IoTProperties for the IoTEntity identified by {IoTEntityId}. These will be wrapped in the parent element ArrayOfIoTProperty.
{base}/IoTEntities/{IoTEntityID}/properties/{IoTPropertyID}
Returns the IoTProperty identified by {IoTEntityId} and {IoTPropertyID}. The @about attribute will be equal to {IoTPropertyId}.
{base}/IoTEntities/{IoTEntityID}/properties/{IoTPropertyID}/observations
Returns a collection of all IoTStateObservations identified by {IoTEntityId} and {IoTPropertyID}. These will be wrapped in the parent element ArrayOfIoTStateObservation. Default order is by descending PhenomenonTime, then ResultTime.
The collection supports filters based on query string parameters in the following way:
?take=x : include up to x elements in the collection. Not supplying this parameter may result in an implicit limit set by the interface implementation (e.g. 500 elements) to enhance responsiveness.
?skip=x : given the other filter parameters and ordering, skip the first x elements in the collection. The parameter take will be applied to the subsequent elements.
?after=x : all elements with PhenomenonTime after this xsd:dateTime.
?before=x : all elements with PhenomenonTime before this xsd:dateTime.