Skip to main content

Settings Backend Java Client

A lightweight Java client for calling the Settings/ABS resolver service from JVM services. It provides a small API to build requests, execute them with Apache HttpClient 5, and parse JSON responses into a simple SettingResponse model.

TL;DR (Kubernetes service-to-service)​

If you call the Settings service from another service inside the cluster, you can use defaults. Just create the client with SettingClientConfiguration.defaults() and do not override anything. All unspecified fields are automatically populated with sensible defaults.

import com.picsart.di.client.config.SettingClientConfiguration;
import com.picsart.di.client.service.SettingService;
import com.picsart.di.client.service.SettingsServiceImpl;
import com.picsart.di.client.model.SettingResponse;
import java.util.Map;

SettingClientConfiguration configuration = SettingClientConfiguration.defaults();
SettingService settingsService = new SettingsServiceImpl(configuration);

// Overload with tag
SettingResponse resp1 = settingsService.getSetting(
    "feature.toggle.newHome",
    "beta",                              // optional tag, can be null or blank
    Map.of("x-user-id", "42")            // optional headers to pass through
);

// Overload without tag
SettingResponse resp2 = settingsService.getSetting(
    "feature.toggle.newHome",
    Map.of("x-user-id", "42")
);

// Read the value and response headers (propagate these headers to your downstream response)
Object value = resp2.value();
Map<String, String> headersToPropagate = resp2.headers();

Installation​

Maven coordinates:

<dependency>
  <groupId>com.picsart</groupId>
  <artifactId>settings-java-client</artifactId>
  <version>0.0.1</version>
</dependency>

Configuration​

Use SettingClientConfiguration to configure the HTTP client. Any value you do not provide is filled from SettingClientProperties. Defaults used when not provided:

Notes:

  • Timeouts are integers consumed by the underlying HTTP client. If you need different behavior, override them explicitly via the builder.
  • For most in-cluster calls you do not need to change these values.

Examples:

import com.picsart.di.client.config.SettingClientConfiguration;

// 1) Use defaults (recommended for k8s service-to-service)
SettingClientConfiguration defaults = SettingClientConfiguration.defaults();

// 2) Custom configuration (override only what you need)
SettingClientConfiguration custom = SettingClientConfiguration.builder()
    .baseUrl("http://my-settings:8080")
    .connectTimeoutMs(2_000)
    .responseTimeoutMs(10_000)
    .maxConnections(100)
    .maxPerRoute(20)
    .build();

Using the client​

import com.picsart.di.client.service.SettingService;
import com.picsart.di.client.service.SettingsServiceImpl;
import com.picsart.di.client.model.SettingResponse;
import java.util.Map;

SettingService service = new SettingsServiceImpl(SettingClientConfiguration.defaults());

// With tag
SettingResponse response1 = service.getSetting(
    "some.setting.name",
    "exp-group-A",
    Map.of("x-user-id", "123")
);

// Without tag (overload)
SettingResponse response2 = service.getSetting(
    "some.setting.name",
    Map.of("x-user-id", "123")
);

Object value = response2.value();
Map<String, String> responseHeaders = response2.headers(); // include these in your outgoing response

Headers and tags​

  • Request headers: you may pass any headers that your service needs for segmentation/identification. They are added to the outgoing request as-is.
  • Response headers: the SDK now returns all response headers in SettingResponse.headers(). If your upstream requires specific headers (e.g., experiment or tracing headers), ensure you propagate them back to your client.
  • The tag parameter is optional. When non-blank, it is sent as a request header named tag.

Endpoints​

Requests are sent to {baseUrl}/api/v1/settings/{name} using HTTP GET.

Error handling​

Non-200 responses or IO problems raise HttpClientException. Ensure you handle this exception at call sites where needed.

Development​

  • Java 17 (via parent POM).
  • Apache HttpClient 5, Jackson 2.17, SLF4J, Lombok.
  • Tests with JUnit Jupiter and Mockito.