Revision for “Retrieving IoTEntity Data” created on December 15, 2014 @ 10:04:50
Title | Retrieving IoTEntity Data |
---|---|
Content | It is possible to access <a title="IoTEntity" href="http://www.iotworldservices.com/wiki/iotworldserviceswiki/getting-and-setting-data-for-iotentities-using-events-and-rest/">IoTEntity </a>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 <strong>GET </strong>request method over HTTP. Similarly, new entities, properties and state observation values can be added using the <strong>POST </strong>request method. The <strong>PUT </strong>request method is used for setting property values, and is thus an enabler for control actions. For these update functions see <a title="Updating IoTEntity Data REST" href="http://www.iotworldservices.com/wiki/iotworldserviceswiki/storage-manager/updating-iotentity-data-rest/">Updating IoTEntity Data REST</a>.
<h2>Object identification - the URI structure</h2>
The URI structure for identification of resources follows the model described in <a href="https://fogbugz.cnet.se/default.asp?W91" data-cke-saved-href="default.asp?W91">IoTEntity - Content Model</a>. The full URI template use a combination of<em> collection names</em> and <em>instance </em>identifiers in the following way:
<code>{base}/IoTEntities/{IoTEntityID}/properties/{IoTPropertyID}/observations</code>
"IoTEntities", "properties" and "observations" denotes <em>collections </em>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.
<h2>Retrieving data - The GET request method</h2>
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:
<code>{base}/IoTEntities/{IoTEntityID}/properties</code>
Below is a complete list of what is returned when the corresponding URI is used in a GET request:
<h3><strong>{base}/IoTEntities</strong></h3>
Returns a collection of all IoTEntities within the scope of the {base}. These will be wrapped in the parent element <a href="https://fogbugz.cnet.se/default.asp?W91" data-cke-saved-href="default.asp?W91">ArrayOfIoTEntity</a>.
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.
<h3><strong>{base}/IoTEntities/{IoTEntityID}</strong></h3>
Returns the <a href="https://fogbugz.cnet.se/default.asp?W91" data-cke-saved-href="default.asp?W91">IoTEntity </a>identified by {IoTEntityId}. The @about attribute will be equal to {IoTEntityId}.
<h3><strong>{base}/IoTEntities/{IoTEntityID}/properties</strong></h3>
Returns a collection of all IoTProperties for the <a href="https://fogbugz.cnet.se/default.asp?W91" data-cke-saved-href="default.asp?W91">IoTEntity </a>identified by {IoTEntityId}. These will be wrapped in the parent element <a href="https://fogbugz.cnet.se/default.asp?W91" data-cke-saved-href="default.asp?W91">ArrayOfIoTProperty</a>.
<h3><strong>{base}/IoTEntities/{IoTEntityID}/properties/{IoTPropertyID}</strong></h3>
Returns the IoTProperty identified by {IoTEntityId} and {IoTPropertyID}. The @about attribute will be equal to {IoTPropertyId}.
<h3><strong>{base}/IoTEntities/{IoTEntityID}/properties/{IoTPropertyID}/observations</strong></h3>
Returns a collection of all IoTStateObservations identified by {IoTEntityId} and {IoTPropertyID}. These will be wrapped in the parent element <a href="https://fogbugz.cnet.se/default.asp?W91" data-cke-saved-href="default.asp?W91">ArrayOfIoTStateObservation</a>. 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. |
Excerpt |