WebServiceProxy and typed invocation

[gk-brown]

Kilo's WebServiceProxy class provides a vehicle for submitting API requests to a server. For example, this code shows how it could be used to access a "sum" endpoint provided by a simple math service:

// GET /math/sum?a=2&b=4
var webServiceProxy = new WebServiceProxy("GET", baseURI.resolve("math/sum"));

webServiceProxy.setArguments(mapOf(
    entry("a", 4),
    entry("b", 2)
));

System.out.println(webServiceProxy.invoke()); // 6.0

While the code is clear and straightforward, it can be simplified. The following code could be used to perform the same operation in a more convenient and type-safe manner:

@ServicePath("math")
public interface MathServiceProxy {
    @RequestMethod("GET")
    @ResourcePath("sum")
    double getSum(double a, double b) throws IOException;
}

var mathServiceProxy = WebServiceProxy.of(MathServiceProxy.class, baseURI);

System.out.println(mathServiceProxy.getSum(4.0, 2.0)); // 6.0

A more practical example can be found here. It uses the Tiingo End-of-Day API to retrieve historical stock pricing information. The proxy interface looks like this:

@ServicePath("tiingo")
public interface TiingoServiceProxy {
    @RequestMethod("GET")
    @ResourcePath("daily/?")
    Asset getAsset(String ticker) throws IOException;

    @RequestMethod("GET")
    @ResourcePath("daily/?/prices")
    List<AssetPricing> getHistoricalPricing(String ticker, LocalDate startDate, LocalDate endDate) throws IOException;
}

It could be used as shown below:

var historicalPricing = tiingoServiceProxy.getHistoricalPricing("AAPL",
    LocalDate.of(2026, 1, 1),
    LocalDate.of(2026, 3, 16));

for (var assetPricing : historicalPricing) {
    System.out.println(String.format("%s %,.2f/%,.2f",
        assetPricing.getDate(),
        assetPricing.getOpen(),
        assetPricing.getClose()));
}

For more information see the README.