API Patterns for accessing thing data in IoT Application Enablement

[marcus_behrens]

Sometimes I felt overwhelmed with the variety of apis that IoT Application Enablement offered for retrieving time series or other data for things. When you look at the help documentation you will find "Read Thing Data" under "Thing", "Times Series Store", "Aggregate Store", "Cold Store", "Time Series OData" and "Composites". There are 14 different apis in these places and how do you know which one is for which use case?

To simplify this search I wrote all of them down in an excel, removed those, that are just variations and ended up with the following 11 apis. I grouped them into apis that provide a history of values, apis that provide a snapshot of values in time and those that aggregate the data. I hope below table it useful to you to find for a given use case the right api:

Pattern	Use Case	What does it do?
History for 1 Thing	Who were prior owners and what were the prior license plates for the car?	Read historic master data values - based on thing ID, thing type and property set	Thing: Master Data and Parameters Data > Read Data for a Thing
History for 1 Thing	When was the car at which geopositions during the course of July 4th 2018?	Read historic measurements from the Warm Store - for a time range - based on thing ID, thing type and property set	Time Series Store > Read Time Series Data or Derived Data for a Thing
History for 1 Thing	What sensor values do we have for the car for the first 2 days of December in 2017?	Read historic measurements from the Cold Store - for a time range - based on thing ID	Time Series Cold Store > Read Time Series Data or Derived Data for a Thing
History across Things	What were the geopositions and timestamps for all cars in the first half of 2018?	Read historic measurements - for a time range - based on property set type	Time Series: OData Service > Measurements > Read Multiple Measurements
Snapshot for 1 Thing	What was the final mileage reading for the car for January 2017?	Read snapshot of most recent master data values or measurements - based on thing ID	Time Series Aggregate Store > Read Snapshot Data Within a Time Range for a Thing
Snapshot for 1 Thing	Give me all the details about ids, registration, sensor data and events for the car!	Read snapshot of most recent master data values, built-in property values, measurements and events - based on thing ID	Composites > Advanced Thing List > Read Property Set Data and Events for a Thing
Snapshot across Things	What registration details (e.g. license plate) were the current ones at the end of 2017 across all cars?	Read snapshot of most recent master data values - based on property set type	Thing: Master Data and Parameters Data > Read Property Set Data
Snapshot across Things	Give me an overview of the current ids and the registration details across all cars!	Read snapshot of most recent master data values and built-in property values - based on property set type and property set	Composites > REST Service > Read Thing Details with Property Set Type Data
Snapshot across Things	Give me an overview of the current ids, the registration details and sensor values across all cars!	Read snapshot of most recent master data values, built-in property values and measurements - based on property set type and property set	Composites > OData Service for Composite Things > Read Things for Property Set of a Property Set Typ...
Aggregation for 1 Thing	What are the extremes for motor and steering sensors for the car in December 2017 if you split up the month into 31 segments across all cars?	Aggregate measurements for minimum, maximum, first and last - for a time range - based on thing ID, thing type and multiple property sets	Time Series Aggregate Store > Read Time Series Data for Multiple Property Types of a Thing Applying ...
Aggregation across Things	What are averages for speed per model and year across all cars?	Aggregate measurements for average, median + 10 more aggregates - for a time range - based on property set type - grouped by time or other dimension properties	Time Series: OData Service > Aggregates > Read Aggregates of Measurements