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" max-retry-timeout = "30 seconds" retries-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()

Please note that 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.

Entity Default Meaning
initTimeout 10 milliseconds initial timout between retries
maxRetryTimeout 30 seconds max timeout between retries
retriesTimeout 10 minutes overall timeout of all retried requests
retrieableHttpErrors [408, 499, 500, 502, 503, 504] set of retriable http errors
retryStrategy exponential strategy of timeouts between retries
maxAttempts 5 max number of retries, 0 means infinite

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

HERE Token
com.here.platform.data.client {
  retry-policy {
    defaults {
      # initial timout between retries
      init-timeout = "10 millis"
      # max timeout between retries
      max-retry-timeout = "30 seconds"
      # overall timeout of all retried requests
      retries-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]
    }
    # example
    # configApi {
    #   defaults { # <<< This applies for any ConfigApi call if there is no policy defined on any other lower level in ConfigApi
    #     init-timeout = "10 millis"
    #     max-retry-timeout = "30 seconds"
    #     retries-timeout = "10 minutes"
    #     retry-strategy = "exponential"
    #     max-attempts = 5
    #     http-retriable-errors = [408, 500]
    #   }
    #   getCatalogs { # <<< This applies for ConfigApi.getCatalogs call
    #     retries-timeout = "30 minutes" # <<< all undefined values come from parent, so from ConfigApi-defaults
    #   }
    # }
  }
}

results matching ""

    No results matching ""