JAVA-260 · Lesson 8 of 12 · 23 min

Calling other services

▶ Video coming soon A video version of this lesson is on the way.

On Wednesday, March 8, Hamza wanted the parts availability endpoint to say when an out-of-stock part could arrive. That meant asking the suppliers. Velotek had a small REST API for stock and delivery dates, and Larchmont Cycle Supply had just opened one. Kofi had learned in the Monday sessions what a slow supplier does to a program that waits patiently, and he had a phrase for it: "Their bad afternoon becomes our bad afternoon." This lesson covers calling other HTTP services from Spring with RestClient and HTTP service clients, and the defensive habits that keep a supplier's problems from becoming the shop's: timeouts, retries with backoff, circuit breakers, validation of what comes back and care with URLs.

A client is a dependency like any other

From the booking service's point of view, Velotek's API is an adapter behind a port, just like the database. The service depends on a SupplierStock interface with a method such as deliveryDate(partCode), and one implementation calls Velotek over HTTP. That keeps the business code testable with a fake and keeps the details of each supplier's JSON in one class. It also gives one place to decide what happens when the supplier is slow, down or wrong, and those decisions matter more than the HTTP code itself.

What can go wrong when calling another service, and the usual protection.
FailureWhat the shop sees without protectionProtection
Supplier is slowEvery availability request waits; request threads pile upConnect and read timeouts
Supplier fails now and thenRandom errors on the websiteA few retries with backoff, for safe requests only
Supplier is down for an hourEvery request waits for a timeout, then failsA circuit breaker that fails fast and a fallback answer
Supplier sends odd dataWrong dates, huge strings or nulls reach the websiteValidate the response like any untrusted input
A caller controls the URLThe server can be made to fetch internal addressesFixed base URLs; no caller-supplied URLs

Timeouts

A call without a timeout can wait for ever. Java's HttpClient has two: a connect timeout on the client for establishing the connection, and a per-request timeout for the whole response to start arriving. The example starts a pretend supplier in the same program with two endpoints, one that answers at once and one that takes two seconds, and calls both with a 300 millisecond request timeout. The slow call fails quickly with HttpTimeoutException, and the service answers with a fallback instead.

Java Example · Main.java
import com.sun.net.httpserver.HttpServer;
import java.net.*;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.concurrent.Executors;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpServer supplier = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        supplier.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        supplier.createContext("/stock/", ex -> {
            String code = ex.getRequestURI().getPath().substring(7);
            if (code.equals("CHAIN-11")) {
                try { Thread.sleep(2000); } catch (InterruptedException e) { return; }
            }
            byte[] body = ("{\"code\":\"" + code + "\",\"delivery\":\"2028-03-14\"}").getBytes(StandardCharsets.UTF_8);
            ex.sendResponseHeaders(200, body.length);
            try (var out = ex.getResponseBody()) { out.write(body); }
        });
        supplier.start();

        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(1)).build();
        String base = "http://127.0.0.1:" + supplier.getAddress().getPort() + "/stock/";
        try {
            for (String code : new String[] {"BELL", "CHAIN-11"}) {
                HttpRequest req = HttpRequest.newBuilder(URI.create(base + code))
                        .timeout(Duration.ofMillis(300)).build();
                try {
                    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
                    System.out.println(code + ": " + res.statusCode() + " " + res.body());
                } catch (HttpTimeoutException e) {
                    System.out.println(code + ": no answer within 300 ms, showing \"delivery date unknown\"");
                }
            }
        } finally {
            supplier.stop(0);
        }
    }
}
Output
BELL: 200 {"code":"BELL","delivery":"2028-03-14"}
CHAIN-11: no answer within 300 ms, showing "delivery date unknown"

What this code does

The pretend supplier runs each request on a virtual thread, and the CHAIN-11 handler sleeps for two seconds before answering. The request timeout of 300 milliseconds makes client.send throw HttpTimeoutException long before that, and the catch block turns it into the fallback message the website would show. The fast BELL request is unaffected by the slow one.

How long should a timeout be? Long enough for the supplier's normal slow answers, short enough that a customer is not left looking at a spinner. Leif measured Velotek over a week: nearly every answer arrived within 400 milliseconds, the slowest within 900. The booking service uses a 2 second connect timeout and a 1 second read timeout, and the website shows "delivery date unknown" rather than waiting longer.

RestClient

Spring Framework 6.1 introduced RestClient, a fluent, synchronous HTTP client, and in Spring Framework 7 it is the recommended choice for blocking code; the older RestTemplate is in maintenance and is planned for deprecation. Spring Boot auto-configures a RestClient.Builder bean with the application's JSON settings, which you customize with a base URL, default headers and a request factory that carries the timeouts.

Java Example · RestClient for Velotek (needs Spring Boot 4)
@Configuration
class SupplierClients {
    @Bean
    RestClient velotek(RestClient.Builder builder, VelotekProperties props) {
        var factory = new JdkClientHttpRequestFactory(
                HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(2)).build());
        factory.setReadTimeout(Duration.ofSeconds(1));
        return builder
                .baseUrl(props.baseUrl())                       // https://api.velotek.example
                .defaultHeader("Authorization", "Bearer " + props.apiKey())   // from the environment
                .requestFactory(factory)
                .build();
    }
}

@Component
class VelotekStock implements SupplierStock {
    private final RestClient velotek;

    VelotekStock(RestClient velotek) { this.velotek = velotek; }

    @Override
    public Optional<LocalDate> deliveryDate(String partCode) {
        VelotekItem item = velotek.get()
                .uri("/v2/stock/{sku}", partCode)
                .retrieve()
                .body(VelotekItem.class);
        return Optional.ofNullable(item).map(VelotekItem::nextDelivery);
    }
}

record VelotekItem(String sku, int available, LocalDate nextDelivery) {}

What this code does

The bean fixes the base URL, the API key header and the timeouts once, so every call through it gets them. uri expands the {sku} template variable with proper encoding, retrieve turns error statuses into exceptions, and body converts the JSON into a record with Jackson. The API key comes from configuration bound from the environment, never from source code.

Spring Framework 7 and Spring Boot 4 also make HTTP service clients easy: you declare a Java interface with @HttpExchange annotations, much like a controller turned inside out, and Spring generates the implementation on top of RestClient. Boot 4's @ImportHttpServices registers such interfaces as beans, with their base URLs and timeouts set per group in configuration.

Java Example · An HTTP service client for Larchmont (needs Spring Boot 4)
@HttpExchange("/v1")
interface LarchmontApi {
    @GetExchange("/items/{code}/availability")
    LarchmontAvailability availability(@PathVariable String code);
}

@Configuration
@ImportHttpServices(group = "larchmont", types = LarchmontApi.class)
class LarchmontConfig { }

What this code does

The interface describes the remote endpoint, and Spring generates a client that sends the request and converts the response. @ImportHttpServices registers the generated client as a bean in a group called larchmont. The group's base URL and timeouts come from configuration properties for that group, so no URL is written in the code.

application.yml (HTTP service client group)
spring:
  http:
    serviceclient:
      larchmont:
        base-url: https://api.larchmont.example
        connect-timeout: 2s
        read-timeout: 1s

What this code does

Each group of HTTP service clients takes its own base URL and timeouts from properties under its group name. Changing a supplier's address or timeouts is a configuration change, not a code change.

Retries with backoff

Some failures are brief: a supplier's server restarts, a network blip drops a connection. Trying again a moment later often works. But retries need rules. Retry only requests that are safe to repeat, such as GET, or a POST that carries an idempotency key the supplier honours. Retry only failures that might go away, such as a timeout, 503 Service Unavailable or 429 Too Many Requests, never a 400 or 404. Wait longer each time, which is exponential backoff, and add jitter, a random part of the wait, so that many clients do not retry in step. And give up after a few attempts.

Java Example · Main.java
import com.sun.net.httpserver.HttpServer;
import java.net.*;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.*;
import java.util.concurrent.atomic.AtomicInteger;

public class Main {
    static final Set<Integer> RETRYABLE = Set.of(429, 502, 503, 504);

    static HttpResponse<String> getWithRetry(HttpClient client, URI uri, int maxAttempts, List<String> log) throws Exception {
        long delay = 50;
        for (int attempt = 1; ; attempt++) {
            HttpResponse<String> res = client.send(HttpRequest.newBuilder(uri).build(), HttpResponse.BodyHandlers.ofString());
            log.add("attempt " + attempt + ": " + res.statusCode());
            if (!RETRYABLE.contains(res.statusCode()) || attempt == maxAttempts) return res;
            log.add("  waiting " + delay + " ms");
            Thread.sleep(delay);
            delay *= 2;
        }
    }

    public static void main(String[] args) throws Exception {
        AtomicInteger calls = new AtomicInteger();
        HttpServer supplier = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        supplier.createContext("/stock/BELL", ex -> {
            boolean ready = calls.incrementAndGet() > 2;
            byte[] body = (ready ? "{\"code\":\"BELL\",\"available\":40}" : "busy").getBytes(StandardCharsets.UTF_8);
            ex.sendResponseHeaders(ready ? 200 : 503, body.length);
            try (var out = ex.getResponseBody()) { out.write(body); }
        });
        supplier.createContext("/stock/HORN", ex -> {
            ex.sendResponseHeaders(404, -1);
            ex.close();
        });
        supplier.start();
        try {
            HttpClient client = HttpClient.newHttpClient();
            String base = "http://127.0.0.1:" + supplier.getAddress().getPort();
            for (String path : List.of("/stock/BELL", "/stock/HORN")) {
                List<String> log = new ArrayList<>();
                HttpResponse<String> res = getWithRetry(client, URI.create(base + path), 4, log);
                System.out.println("GET " + path);
                log.forEach(l -> System.out.println("  " + l));
                System.out.println("  result: " + res.statusCode() + " " + res.body());
            }
        } finally {
            supplier.stop(0);
        }
    }
}
Output
GET /stock/BELL
  attempt 1: 503
    waiting 50 ms
  attempt 2: 503
    waiting 100 ms
  attempt 3: 200
  result: 200 {"code":"BELL","available":40}
GET /stock/HORN
  attempt 1: 404
  result: 404

What this code does

The pretend supplier answers 503 to the first two requests for BELL and 200 after that. getWithRetry retries only the statuses in RETRYABLE, doubling the wait each time, so BELL succeeds on the third attempt after waits of 50 and 100 milliseconds. The 404 for HORN is not retryable, so it is returned after one attempt, since asking again would not make the part exist.

The example leaves out jitter so that its output is the same on every run. A real retry policy multiplies each delay by a random factor, for example between 0.5 and 1.5. Spring Framework 7 brought retry support into the core framework, with a RetryTemplate and an @Retryable annotation that can be switched on with @EnableResilientMethods, along with @ConcurrencyLimit for capping parallel calls.

Java Example · Declarative retry in Spring Framework 7 (needs Spring Framework 7)
@Retryable(includes = SupplierUnavailable.class, maxRetries = 3, delay = 100, multiplier = 2, jitter = 50)
public Optional<LocalDate> deliveryDate(String partCode) {
    return velotekStock.deliveryDate(partCode);
}

What this code does

The annotation asks Spring to call the method again when it throws SupplierUnavailable, up to three more times, starting with a 100 millisecond delay that doubles each time and varies by up to 50 milliseconds. Only that exception triggers a retry, so a not-found answer fails at once. The method only reads, so repeating it is safe.

Circuit breakers

Retries help with brief failures but make long ones worse: if Velotek is down for an hour, every request now waits for several timeouts instead of one. A circuit breaker watches the results of calls. While calls succeed it is closed and lets them through. After a run of failures it opens, and for a while every call fails immediately without touching the network, so the service answers quickly with its fallback. After a cool-down it goes half-open and lets one trial call through: success closes it again, failure opens it again. Resilience4j is the library most Spring applications use for this, through its Spring Boot starter.

Java Example · Main.java
import java.util.*;

public class Main {
    enum State { CLOSED, OPEN, HALF_OPEN }

    static class CircuitBreaker {
        private final int failureThreshold;
        private final long openMillis;
        private State state = State.CLOSED;
        private int failures = 0;
        private long openedAt = 0;

        CircuitBreaker(int failureThreshold, long openMillis) {
            this.failureThreshold = failureThreshold;
            this.openMillis = openMillis;
        }

        String call(long now, boolean supplierUp) {
            if (state == State.OPEN) {
                if (now - openedAt < openMillis) return "fallback (open, not calling)";
                state = State.HALF_OPEN;
            }
            if (supplierUp) {
                state = State.CLOSED;
                failures = 0;
                return "ok";
            }
            failures++;
            if (state == State.HALF_OPEN || failures >= failureThreshold) {
                state = State.OPEN;
                openedAt = now;
            }
            return "failed, then fallback";
        }
    }

    public static void main(String[] args) {
        CircuitBreaker cb = new CircuitBreaker(3, 30_000);
        long[] times =      {0,    1000,  2000,  3000,  4000,  35_000, 36_000, 70_000};
        boolean[] upAt =    {true, false, false, false, false, false,  false,  true};
        for (int i = 0; i < times.length; i++) {
            String result = cb.call(times[i], upAt[i]);
            System.out.printf("t=%2ds supplier %-4s -> %-30s state %s%n", times[i] / 1000, upAt[i] ? "up" : "down", result, cb.state);
        }
    }
}
Output
t= 0s supplier up   -> ok                             state CLOSED
t= 1s supplier down -> failed, then fallback          state CLOSED
t= 2s supplier down -> failed, then fallback          state CLOSED
t= 3s supplier down -> failed, then fallback          state OPEN
t= 4s supplier down -> fallback (open, not calling)   state OPEN
t=35s supplier down -> failed, then fallback          state OPEN
t=36s supplier down -> fallback (open, not calling)   state OPEN
t=70s supplier up   -> ok                             state CLOSED

What this code does

The breaker counts consecutive failures and opens after three, after which calls at four seconds and at 36 seconds return the fallback at once without contacting the supplier. At 35 seconds the 30 second cool-down has passed, so one trial call goes through; it fails and the breaker opens again. At 70 seconds the next trial succeeds and the breaker closes, and the time is passed in as a number so the run is the same every time.

A state diagram with three circles: Closed, Open and Half-open. An arrow from Closed to Open is marked three failures in a row. An arrow from Open to Half-open is marked after the cool-down. From Half-open, an arrow back to Closed is marked trial call succeeds and an arrow back to Open is marked trial call fails. A note under Open reads fail fast with the fallback.
The three states of a circuit breaker and the events that move it between them.

Distrust what comes back

API10:2023 Unsafe Consumption of APIs is the OWASP risk of trusting a third party's data more than a user's. A supplier's response is input from outside, so the booking service validates it just as it validates a booking request: the delivery date must parse and must be within the next ninety days, quantities must not be negative and text must have a length limit. A response that fails is treated like a failed call, and the fallback is shown.

API7:2023 Server Side Request Forgery (SSRF) is the risk of letting a caller decide which URL the server fetches. If an endpoint took a supplier URL as a parameter, an attacker could point it at an internal address such as the database host or a cloud metadata service and read the result through the shop's API. The booking service never builds a URL from user input: base URLs come from configuration and only path variables are filled in, with encoding. Spring Boot 4.1 added a further safeguard, a filter on outgoing client connections that can block private and internal addresses.

Try it yourself

Compute the backoff

Complete delay so that attempt 1 waits base milliseconds and each later attempt waits twice as long as the one before, but never more than cap.

Print the waits for attempts 1 to 7 with a base of 100 and a cap of 2,000.

public class Main {
    static long delay(int attempt, long base, long cap) {
        return base;
    }

    public static void main(String[] args) {
        StringBuilder sb = new StringBuilder();
        for (int a = 1; a <= 7; a++) sb.append("attempt ").append(a).append(": ").append(delay(a, 100, 2000)).append(" ms\n");
        System.out.print(sb);
    }
}

Try it yourself

Check the supplier response

Complete check so that it returns ok for a sensible response and otherwise a reason: bad date if the date does not parse, date out of range if it is before today or more than 90 days after it, and negative quantity if available is below 0.

Check in that order.

import java.time.*;
import java.time.format.DateTimeParseException;

public class Main {
    record SupplierItem(String code, int available, String nextDelivery) {}

    static String check(SupplierItem item, LocalDate today) {
        return "ok";
    }

    public static void main(String[] args) {
        LocalDate today = LocalDate.of(2028, 3, 8);
        SupplierItem[] items = {
            new SupplierItem("CHAIN-11", 0, "2028-03-14"),
            new SupplierItem("GRIPS", 5, "14/03/2028"),
            new SupplierItem("BELL", 12, "2031-01-01"),
            new SupplierItem("TUBE-700", -4, "2028-03-20")
        };
        for (SupplierItem i : items) System.out.println(i.code() + ": " + check(i, today));
    }
}

By the end of the evening the availability endpoint answered "out of stock, expected March 14" for CHAIN-11, and Hamza had unplugged the network cable to check that it said "delivery date unknown" within a second instead of hanging. Kofi made him do it twice.

Common mistakes

  • MistakeCalling another service without timeouts.

    InsteadSet a connect timeout and a read timeout on every client.

  • MistakeRetrying every failure, including 400 and 404.

    InsteadRetry only failures that may pass, such as timeouts, 429 and 503, and only safe requests.

  • MistakeRetrying immediately and for ever.

    InsteadUse exponential backoff with jitter and a small maximum number of attempts.

  • MistakeTrusting a supplier's JSON because the supplier is a partner.

    InsteadValidate third-party responses like any other input.

  • MistakeBuilding outgoing URLs from request parameters.

    InsteadUse fixed base URLs from configuration and fill only encoded path variables.

Summary and key terms

  • Another service is a dependency behind a port, called from one adapter class.
  • Every call needs a connect timeout and a read timeout, and a fallback answer for when they fire.
  • RestClient is Spring's fluent synchronous client, configured once as a bean with a base URL, headers and timeouts; HTTP service clients generate implementations from @HttpExchange interfaces, registered in Boot 4 with @ImportHttpServices.
  • Retries suit brief failures of safe requests: retry only retryable statuses, use exponential backoff with jitter and give up after a few attempts; Spring Framework 7 adds @Retryable.
  • A circuit breaker opens after repeated failures to fail fast, then half-opens for a trial call.
  • Responses from other APIs are validated (OWASP API10), and outgoing URLs never come from callers (API7, SSRF).
RestClient
Spring's fluent, synchronous HTTP client.
HTTP service client
A generated client implementing an interface annotated with @HttpExchange.
Connect timeout
The longest time to wait while establishing a connection.
Read timeout
The longest time to wait for a response once connected.
Exponential backoff
Waiting longer before each retry, typically doubling the delay.
Jitter
A random variation added to retry delays so clients do not retry together.
Idempotency key
A client-chosen ID that lets a server recognize and ignore a repeated request.
Circuit breaker
A guard that stops calling a failing service for a while and fails fast instead.
Fallback
The answer used when a call fails or is skipped.
SSRF
Server-side request forgery: making a server fetch a URL chosen by an attacker.

Practice problems

Work each problem on paper first, then reveal the answer to check.

  1. Name the two kinds of timeout on Java's HttpClient.

    Show answer

    The connect timeout on the client and the per-request timeout.

  2. Should the service retry a 404 from a supplier?

    Show answer

    No; the answer will not change.

  3. Why add jitter to backoff?

    Show answer

    So that many clients do not retry at the same moment.

  4. What does a circuit breaker do when it is open?

    Show answer

    Fails calls immediately with the fallback, without contacting the service.

  5. How does the booking service avoid SSRF?

    Show answer

    It never builds outgoing URLs from caller input; base URLs come from configuration.

Lesson quiz · 5 questions

Score 60% or more to complete this lesson.

Take the quiz