Bosch IoT Insights

Configuring a custom endpoint

Custom (dynamic) endpoints are user-defined REST endpoint paths which trigger the execution of a query template. The URL provided in the Path property is called via the HTTP GET request to execute the query template.

images/confluence/download/attachments/1632456259/explore_query_template_custom_endpoint_2021_03_12.png

Prerequisites

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

    If other API users should be able to execute the endpoint, activate the Share with other project members checkbox in the query template.

  • In the query template settings, you have activated the Enable custom endpoint switch, refer to Creating a query template.

Setting the parameters

The parameters that shall be part of the custom endpoint path can only be of the parameter types SCALAR and LIST. MAP and RANGE parameter types are not supported and will be ignored. If these parameters are set to mandatory (Optional checkbox not activated), the query template cannot be created.

Parameters can also be provided in a query string when calling the custom endpoint. In fact, the only way to provide a LIST parameter is in the query string, e.g. /api/example/path?myList=one&myList=two&myList=three.

When calling the endpoint, all defined path parameters must be provided.

Setting the custom endpoint path

The Path field defines the path or URL pattern which will execute the query template when called. It can contain as many path segments as needed. Path parameters should be put in curly braces (“{}”) and their names should match the exact names of the query template parameters they correspond to.

The use of a query string is supported and taken into account when invoking the custom endpoint, but it should not be given as part of the Path field in the Template Designer.

The full request URL is constructed the following way: <InsightsAddress>/r/<projectName>/<customPath>.

When a custom endpoint is invoked, every mandatory query template parameter is firstly searched in the path params. If not provided there, the query string is checked. If not present there as well, an HTTP status code of 400 “Bad request” is returned due to the missing mandatory parameter.

Asterisk matchers (e.g. api/test/**) as well as duplicate paths are not supported as parameter names are not part of the uniqueness check (only path segment names and count).

For example, the following two paths are duplicates and will not be allowed:

  • api/test/{param1}/{param2}

  • api/test/{a}/{b}


In the Examples chapter, you can find an example on how to configure a custom endpoint, refer to the Data Explorer: Configuring a custom endpoint page.