This example describes the process of configuring a custom endpoint for a query template in the Data Explorer.

Bosch IoT Insights can process, for instance, geographical and geological data of mountains around the world. Every mountain has its own characteristics, such as height, snow coverage, discovery date, and the location. A query template can be created to retrieve the data using the MongoDB query language. An external system or client then executes the query template with the desired parameters by invoking the custom endpoints' URL.

In this example, we will add the following parameters:

minHeight
maxHeight
continent
snowCover
discoveredAfter

Prerequisites

You need to have an API user to execute the custom endpoint.

Creating the query template

Click the Data Explorer menu item.
→ The Data Explorer is displayed and shows existing query templates.
Click the Add Query Template button.
→ The Template Designer is displayed.
In the Basic Details pane, provide general information on the query template.
1. In the Name field, enter a name for the query template.
2. In the Collection drop-down list, select a collection that shall be queried.
3. In the Description field, add a description for the query template.
4. Activate the Share with other project members checkbox if other API users should also be able to execute the endpoint.
In the Parameters pane, add the parameters to receive data for a specific value with the query template.
1. Click the Add parameter button for each of the five parameters to be added one by one.
  → The Edit Parameter dialog is displayed.
2. In the Technical Name field, enter the technical names of the following parameters:
  - minHeight
  - maxHeight
  - continent
  - snowCover
  - discoveredAfter
3. In the Data type drop-down list, select the following data types for each parameter:
  - minHeight: INT
  - maxHeight: INT
  - continent: STRING
  - snowCover: BOOLEAN
  - discoveredAfter: TIMESTAMP
4. In the Parameter Type drop-down list, select the following parameter types for each parameter:
  - minHeight: SCALAR
  - maxHeight: SCALAR
  - continent: SCALAR
  - snowCover: SCALAR
  - discoveredAfter: SCALAR
5. Activate the Optional checkbox to define the parameters as optional.
6. Click the Save button to add each parameter.
  → The parameters are added.
In the Custom Endpoint pane, activate the Enable custom endpoint switch to execute the query template by calling the customized URL.

The Insights Endpoint URL is already pre-filled. The URL is always structured as follows: <InsightsAddress>/r/<projectName>.
1. In the Path field, enter the path with all mandatory parameters in curly brackets separated by a slash.
Click the Create New Query Template button to create the query template.

Invoking the custom endpoint

After saving the query template, the custom endpoint path can be invoked with an HTTP GET request.

The full request URL is constructed as follows: <InsightsAddress</r/<projectName>/<customPath>

The custom path refers to the path as entered in the Path field: geo/mountain/{continent}/{minHeight}/{maxHeight}

The query template can now be executed by calling the following URL: https://bosch-iot-insights.com/r/<projectName>/geo/mountain/Europe/1500/4000

The parameters are mapped. The query template is executed with the following parameter values:

continent=Europe
minHeight=1500
maxHeight=4000

You can also provide the two parameters we marked as optional: https://bosch-iot-insights.com/r/<projectName>/geo/mountain/Europe/1500/4000?discoveredAfter=1970-02-22T15:50:43.665Z&snowCover=false

The parameters are mapped. The query template is executed with the following parameter values:

continent=Europe
minHeight=1500
maxHeight=4000
discoveredAfter=1970-02-22T15:50:43.665Z
snowCover=false