Data Client Base Library request configuration

The Data Client Base Library supports very fine-grained configuration that can be used to tune the settings for HTTP requests on multiple levels.

These settings can be defined using application.conf resource or programmatically in the application code. If there are settings defined by the user some hard-coded default settings apply which are meaningful for most of the use-cases.

The order of usage of settings from different resources is

• Hard-coded default settings are overruled by
• Settings defined in application.conf are overruled by
• Settings defined in application code

The multiple levels at which the settings can defined which are

1. Base Client level

   Settings at this level are applied globally, i.e. to all APIs and endpoints which are support by Data Client Base Library.

   com.here.platform.data.client.retry-policy.defaults { init-timeout = "10
   millis" request-timeout = "30 seconds" overall-timeout = "10 minutes"
   retry-strategy = "exponential" max-attempts = 5 http-retriable-errors = [408,
   499, 500, 502, 503, 504] }

-- or --

baseClient = BaseClient().withConfig(ApiConfiguration(...))

2. API level

   Settings at this level are applied to all endpoint of a specific API only.

   com.here.platform.data.client.retry-policy.BlobApi.defaults { ... }

-- or --

blobApi = baseClient.of[BlobApi].withConfig(ApiConfiguration(...))

3. Endpoint level

   Settings at this level are applied to a specific endpoint only.

   com.here.platform.data.client.retry-policy.BlobApi.putBlob { ... }

-- or --

blobApi.putBlob(...).withConfig(ApiConfiguration(...)).executeToEntity()

If you need to execute a specific single request instance with specific settings (e.g. for debugging) you can do that only by programmatically defining these settings in your application code.

The order of usage of settings is applied on each level individually. As an example, consider the following use case:

Let's say you can have no settings at Base Client level thus hard-coded defaults apply. Then you have define some settings for BlobApi in your application.conf and additionally some very specific settings for putBlob endpoint in your application code. Now, if you execute a request to putBlob endpoint there will apply the very specific setting you have in your application code. If you execute a request to any other endpoint of BlobApi (e.g. getBlob) then the specific settings from your application.conf will apply. If you execute a request to any other API then the default setting will apply.

Per-Request configuration entities

Currently, this fine-grained configuration applies to retry policy only. The following table describes the Retry policy parameters.

Predefined retry strategies

• exponential: retry timeout grows exponential with 2 to the power of (number of retries - 1)
• geometric: retry timeout grows linear with factor 2 and number of retries
• never: never retry

Example using application.conf

com.here.platform.data.client {
  request {
    defaults {
      retry-policy {
        # initial timeout between retries
        init-timeout = "10 millis"
        # max timeout between retries
        request-timeout = "30 seconds"
        # overall timeout of all retried requests
        overall-timeout = "10 minutes"
        # strategy of increasing timeouts between retries
        retry-strategy = "exponential"
        # max number of retries, 0 is infinite
        max-attempts = 5
        # http retriable errors
        http-retriable-errors = [408, 499, 500, 502, 503, 504]
      }
      # The time after which the blocking request will be failed
      blocking-timeout = "5 minutes"
    }
    # example
    # configApi {
    #   defaults { # <<< This applies for any ConfigApi call if there is no policy defined on any other lower level in ConfigApi
    #     retry-policy {
    #       init-timeout = "10 millis"
    #       request-timeout = "30 seconds"
    #       overall-timeout = "10 minutes"
    #       retry-strategy = "exponential"
    #       max-attempts = 5
    #       http-retriable-errors = [408, 500]
    #     }
    #     blocking-timeout = 1 minutes
    #   }
    #   getCatalogs { # <<< This applies for ConfigApi.getCatalogs call
    #     retry-policy {
    #       overall-timeout = "30 minutes" # <<< all undefined values come from parent, so from ConfigApi-defaults
    #     }
    #     blocking-timeout = 30 seconds
    #   }
    # }
  }
}