spring-boot-http-client

Spring Boot HTTP Client

Naming Conventions

• Suffix HTTP client classes with HttpClient.
• Suffix HTTP adapter classes with HttpAdapter.
• Suffix HTTP configuration properties classes with HttpProperties.
• Name HTTP client @Configuration classes with the *HttpConfiguration suffix (e.g., UserHttpConfiguration, PaymentHttpConfiguration).

Rules

• Keep outbound client configuration centralized in a dedicated configuration class.
• Use RestClient (Spring Framework 6.1+) as the default for imperative HTTP calls.
• Use WebClient only when reactive streams are required.
• Keep endpoint URLs and credentials externalized in properties.
• Bind HTTP client properties using @ConfigurationProperties annotated with @Validated.
• Keep external-call initialization explicit and deterministic.
• Inject RestClient.Builder into the service class and construct the RestClient instance in a @PostConstruct method using the bound properties.
• Keep outbound connection and read timeout values explicit and externally configurable.
• Use connectionTimeout=5s and readTimeout=30s as default timeout values unless the remote API's SLA explicitly requires different values.
• Keep error handling explicit for non-success HTTP responses.
• Register .onStatus() handlers on every RestClient call chain to map HTTP error responses to domain exceptions before they propagate to the service caller.
• Keep status-specific failure mapping explicit when remote APIs expose known error classes.
• Apply retry logic only for idempotent HTTP methods (GET, PUT, DELETE, HEAD), or for POST/PATCH when the remote API explicitly confirms idempotency.
• Keep generic response mapping type-safe.
• Use ParameterizedTypeReference for all generic response types (e.g., List<T>, PagedModel<EntityModel<T>>) to preserve type information at deserialization.
• Keep outbound request construction isolated from the controller layer.
• Use UriComponentsBuilder for all dynamic URL construction in outbound calls.