With the HttpDataProvider you can access arbitrarily configurable HTTP/HTTPS endpoints. In the simplest kind of configuration, you specify a destination address and then convert the resulting data into contacts. Since many services require authentication, the provider allows you to define a sequence of HTTP requests to fetch "access tokens" or other data and use it for further HTTP requests.

Configuration

In addition to the Mapping and SearchParameters configuration, which all DataProviders of the Data interface require, the HttpDataProvider can be configured via the Option element:

<HttpDataProvider DisplayName="Customer addresses">
  <Configuration>
    ...
  </Configuration>
  ...
</HttpDataProvider>

Configuration In this part the sequence of HTTP requests is defined.

Secret To avoid plain text passwords in configurations, secrets can be added as <Secret Name="..." Value="{c[...]}" />. At runtime the password is decrypted and can be used as a placeholder for Requests.
Step A step comprises a Request and a Response. An unlimited number of steps can be defined. During each step Properties or Contacts can be added to the result list.
- Request This element is used to build the HTTP request.
  - Method (attribute) HTTP method to be used (GET, POST, ...)
  - Url (attribute) Target URL of the request. Placeholders can be used in the URL using this notation: {Placeholder}. Placeholders are always URL-encoded.
  - Header Any number of HTTP headers can be specified. Placeholders can also be used via the {Placeholder} syntax.
  - Body A body can be defined. Placeholders can also be used via the {Placeholder} syntax. No encoding is done here.
  - FakeResponse To test an endpoint, the FakeResponse element can be used to define a configurable return value.
- Response The Response can be used to access the HTTP response. A Response can either create one or more Property elements or perform a data mapping.
  - Property This element can be used to retrieve a specific value from the HTTP response using a JsonPath or an XPath. The value is then available via the {Placeholder} for further requests under the configured name.
  - Data The actual data is searched for via this element. A JsonPath or an XPath must be specified here. The data is then converted via the Mapping for the Schema of the Object / ObjectCollection.

Example

<HttpDataProvider DisplayName="TelSearch">
  <SearchParameters>
    <Text Id="What" Label="Search term" />
  </SearchParameters>
  <Configuration>
    <Step>
      <Request Method="Get">
        <Url><![CDATA[https://tel.search.ch/api/?was={What}&key=[Key]&maxnum=100]]></Url>
      </Request>
      <Response>
        <Data XPath="*[local-name()='feed']/*[local-name()='entry']">
          <Mapping>
            <Map Source="*[local-name()='name']" Target="CompanyName" />
            <Map Target="Street">
              <Map.SourceExpression><![CDATA[
                function main()
                {
                  const street = source("*[local-name()='street']");
                  const streetno = source("*[local-name()='streetno']");
                  return street + " " + streetno; 
                }
              ]]></Map.SourceExpression>
            </Map>
            <Map Source="*[local-name()='zip']" Target="PostalCode" />
            <Map Source="*[local-name()='city']" Target="City" />
            <Map SourceValue="CH" Target="Country" />
          </Mapping>
        </Data>
      </Response>
    </Step>
  </Configuration>
</HttpDataProvider>