Request Customization

About

RestTemplate provides several hooks and constructs to allow request customization a critical aspect when interacting with external APIs or internal microservices that require authentication, custom headers, request transformations, logging, tracing, or advanced configuration like timeouts and interceptors.

Customizing a request ensures that our API calls are:

Secure (e.g., with bearer tokens or API keys),
Compliant (e.g., with required content-type or correlation IDs),
Reliable (e.g., with retries, timeouts, and fallbacks),
Traceable (e.g., with custom headers for distributed tracing).

Common Use Cases

Use Case

Customization Example

Add Path and Query Param

Set Query, Path parameters

Add Request Body

Set API Request body

Add authentication headers

Bearer token, API key, Basic Auth

Include trace/correlation IDs

Pass unique request ID for observability

Change content type / accept type

application/json, application/xml, custom media types

Modify request payload

Pre-serialize object, or add additional request fields

Set timeouts or connection pool

Customize via underlying HttpClient or RestTemplateBuilder

Pre-process request before sending

Interceptors, ClientHttpRequestInterceptor

Add dynamic headers from context

Extract values from MDC, ThreadLocal, or SecurityContext

Add Path and Query Param

When interacting with external or internal REST APIs, it is common to dynamically construct the request URL by appending:

Path Parameters — values embedded directly within the URL path (e.g., /user/{id}),
Query Parameters — key-value pairs appended after the ? in the URL (e.g., ?status=active&limit=10).

Spring’s RestTemplate provides multiple ways to inject these parameters cleanly and maintainably.

1. Using Path Variables with URI Template Expansion

This is the most common and safe way to replace path variables in endpoint templates using placeholders.

String url = "https://api.example.com/users/{userId}/orders/{orderId}";
Map<String, String> uriVariables = Map.of(
    "userId", "12345",
    "orderId", "987"
);

ResponseEntity<OrderResponse> response = restTemplate.getForEntity(
    url,
    OrderResponse.class,
    uriVariables
);

Path placeholders ({userId}, {orderId}) are automatically replaced by values from the Map.
No need for string concatenation.
Prevents URL injection or malformed paths.

2. Path Params via `UriComponentsBuilder` for Dynamic URIs

Use UriComponentsBuilder when we want to construct complex URLs that include both path variables and query parameters dynamically.

URI uri = UriComponentsBuilder
    .fromUriString("https://api.example.com/users/{userId}/orders")
    .queryParam("page", 1)
    .queryParam("limit", 50)
    .queryParam("sortBy", "date")
    .buildAndExpand("12345")
    .toUri();

ResponseEntity<OrderList> response = restTemplate.getForEntity(uri, OrderList.class);

buildAndExpand("12345") replaces {userId}.
queryParam() is used for clean and safe appending of query parameters.
Works great for pagination, filtering, and sorting APIs.

3. Fully Programmatic Path + Query Construction

This is helpful when query params are optional or dynamically built based on logic:

MultiValueMap<String, String> queryParams = new LinkedMultiValueMap<>();
queryParams.add("category", "books");
queryParams.add("sort", "title");
queryParams.add("sort", "price"); // multiple values for same key

URI uri = UriComponentsBuilder
    .fromUriString("https://api.example.com/users/{userId}/cart")
    .queryParams(queryParams)
    .buildAndExpand("u7890")
    .encode()
    .toUri();

ResponseEntity<CartResponse> response = restTemplate.exchange(
    uri,
    HttpMethod.GET,
    null,
    CartResponse.class
);

MultiValueMap handles multiple query parameters with the same key.
encode() ensures proper URI encoding for special characters.

4. Mixing Path and Query Params in POST Request

Even in POST calls (or PUT), query parameters are often used for metadata like versioning or flags.

URI uri = UriComponentsBuilder
    .fromUriString("https://api.example.com/users/{id}/upload")
    .queryParam("async", "true")
    .queryParam("version", "v2")
    .buildAndExpand("user123")
    .toUri();

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
HttpEntity<FileUploadRequest> request = new HttpEntity<>(fileRequest, headers);

ResponseEntity<FileUploadResponse> response = restTemplate.exchange(
    uri,
    HttpMethod.POST,
    request,
    FileUploadResponse.class
);

Add Request Body

When making HTTP methods like POST, PUT, or PATCH, the client often needs to send a structured request body typically in JSON or XML format. This body carries the actual business payload (e.g., user details, payment data, file metadata).

Spring’s RestTemplate allows for seamless serialization of Java objects into the body of a request using its built-in message converters (usually MappingJackson2HttpMessageConverter for JSON).

HttpEntity<T> is used to encapsulate:
- Body – the Java object (payload).
- Headers – content type, authentication, etc.
Always specify Content-Type (application/json) to avoid serialization issues.

1. POST Request with JSON Body

UserCreateRequest user = new UserCreateRequest("john.doe", "password123");

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);

HttpEntity<UserCreateRequest> requestEntity = new HttpEntity<>(user, headers);

ResponseEntity<UserResponse> response = restTemplate.postForEntity(
    "https://api.example.com/users",
    requestEntity,
    UserResponse.class
);

user is automatically serialized into JSON.
The content-type is declared explicitly.
Response is mapped to UserResponse.

2. PUT Request with Request Body

UserUpdateRequest updateRequest = new UserUpdateRequest("john.doe", "[email protected]");

HttpEntity<UserUpdateRequest> entity = new HttpEntity<>(updateRequest);

restTemplate.put("https://api.example.com/users/{id}", entity, "123");

PUT operations use restTemplate.put().
Path variable ({id}) is passed separately.

3. Exchange Method for Full Control (POST, PUT, PATCH)

For advanced use cases like:

Passing custom headers
Supporting non-JSON content
Handling dynamic URLs

Use exchange() method:

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
headers.set("X-Correlation-Id", "txn-456789");

PaymentRequest payload = new PaymentRequest("user123", 100.0);

HttpEntity<PaymentRequest> request = new HttpEntity<>(payload, headers);

URI uri = UriComponentsBuilder
    .fromUriString("https://api.example.com/payments?async=true")
    .build()
    .toUri();

ResponseEntity<PaymentResponse> response = restTemplate.exchange(
    uri,
    HttpMethod.POST,
    request,
    PaymentResponse.class
);

4. Sending a List or Collection in Request Body

For APIs that accept arrays or lists:

List<String> userIds = List.of("u123", "u124", "u125");

HttpEntity<List<String>> request = new HttpEntity<>(userIds);

ResponseEntity<GroupResponse> response = restTemplate.postForEntity(
    "https://api.example.com/groups/{groupId}/users",
    request,
    GroupResponse.class,
    "teamA"
);

5. Sending a Form-Encoded Body (Non-JSON)

If the backend expects a URL-encoded form body:

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
map.add("username", "john");
map.add("password", "secret");

HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(map, headers);

ResponseEntity<TokenResponse> response = restTemplate.postForEntity(
    "https://auth.example.com/oauth/token",
    request,
    TokenResponse.class
);

Add authentication headers

In most enterprise applications, outbound HTTP requests need to include authentication details—whether via Bearer tokens, API keys, Basic Auth, or custom headers—to access protected APIs.

Spring’s RestTemplate allows injecting headers easily via HttpHeaders, which are then bundled with the request body using HttpEntity.

Headers are included using HttpHeaders, which supports all standard and custom header types.
Auth headers are most often added as:
- Authorization: Bearer <token> (OAuth/JWT)
- Authorization: Basic <base64> (Basic Auth)
- X-API-Key: <key> (Custom API key)
HttpEntity is used to combine headers and optional body for request.

1. Bearer Token Authentication

Used widely with OAuth 2.0, JWT, and internal token-based auth:

HttpHeaders headers = new HttpHeaders();
headers.setBearerAuth("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");

HttpEntity<Void> entity = new HttpEntity<>(headers);

ResponseEntity<AccountResponse> response = restTemplate.exchange(
    "https://api.example.com/accounts/{id}",
    HttpMethod.GET,
    entity,
    AccountResponse.class,
    "acc123"
);

setBearerAuth() automatically adds the header: Authorization: Bearer <token>

2. Basic Authentication

For services still using basic HTTP authentication:

String plainCreds = "username:password";
String base64Creds = Base64.getEncoder().encodeToString(plainCreds.getBytes());

HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "Basic " + base64Creds);

HttpEntity<Void> entity = new HttpEntity<>(headers);

ResponseEntity<EmployeeData> response = restTemplate.exchange(
    "https://internal.example.com/employees",
    HttpMethod.GET,
    entity,
    EmployeeData.class
);

Encodes the string as Authorization: Basic <encoded-credentials>

3. API Key as Header

Some services use API keys passed in custom headers like X-API-Key or x-client-secret:

HttpHeaders headers = new HttpHeaders();
headers.add("X-API-Key", "api-key-987654321");

HttpEntity<Void> request = new HttpEntity<>(headers);

ResponseEntity<InvoiceResponse> response = restTemplate.exchange(
    "https://thirdparty.com/invoices",
    HttpMethod.GET,
    request,
    InvoiceResponse.class
);

4. With Request Body and Auth Headers (POST)

When sending both payload and headers:

PaymentRequest payment = new PaymentRequest("txn789", 150.00);

HttpHeaders headers = new HttpHeaders();
headers.setBearerAuth("secure-token-123");
headers.setContentType(MediaType.APPLICATION_JSON);

HttpEntity<PaymentRequest> requestEntity = new HttpEntity<>(payment, headers);

ResponseEntity<PaymentResponse> response = restTemplate.postForEntity(
    "https://api.example.com/payments",
    requestEntity,
    PaymentResponse.class
);

5. Dynamically Inject Headers via Interceptor (Reusable)

If every request should carry a token:

public class AuthInterceptor implements ClientHttpRequestInterceptor {
    @Override
    public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution)
            throws IOException {
        request.getHeaders().setBearerAuth("dynamic-token-here");
        return execution.execute(request, body);
    }
}

RestTemplate restTemplate = new RestTemplate();
restTemplate.getInterceptors().add(new AuthInterceptor());

Recommended when a common token applies to all requests.
Encouraged over repeating header logic in every request.

Include trace/correlation IDs

In distributed systems and microservices, correlation IDs (also called trace IDs or request IDs) are essential for request tracking, observability, debugging, and log correlation across service boundaries.

When making HTTP calls using RestTemplate, it's a common practice to propagate the correlation ID received in the incoming request to any downstream services.

1. Manually Add a Correlation ID to Headers

If the correlation ID is generated earlier (e.g., in a filter or controller), inject it into outgoing request headers.

String correlationId = MDC.get("X-Correlation-ID"); // From thread-local logging context

HttpHeaders headers = new HttpHeaders();
headers.add("X-Correlation-ID", correlationId);

HttpEntity<Void> entity = new HttpEntity<>(headers);

ResponseEntity<CustomerResponse> response = restTemplate.exchange(
    "https://api.partner.com/customers/{id}",
    HttpMethod.GET,
    entity,
    CustomerResponse.class,
    "cust-101"
);

Header Name: Use a consistent name like X-Correlation-ID or traceId.

2. Automatically Inject Correlation ID via Interceptor

To avoid repeating this logic everywhere, use a ClientHttpRequestInterceptor:

public class CorrelationIdInterceptor implements ClientHttpRequestInterceptor {
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException {
        
        String correlationId = MDC.get("X-Correlation-ID");
        if (correlationId != null) {
            request.getHeaders().add("X-Correlation-ID", correlationId);
        }

        return execution.execute(request, body);
    }
}

@Bean
public RestTemplate restTemplate() {
    RestTemplate restTemplate = new RestTemplate();
    restTemplate.getInterceptors().add(new CorrelationIdInterceptor());
    return restTemplate;
}

Now every outbound call via RestTemplate will carry the correlation ID.

3. Integration with Spring Cloud Sleuth

If we use Spring Cloud Sleuth, it automatically manages trace IDs and span IDs:

X-B3-TraceId: 7b63a1d95e0e33c7
X-B3-SpanId: d7a1fbea4e3fa0b7
X-B3-Sampled: 1

We can keep this in sync with our custom X-Correlation-ID by configuring MDC.

4. Handling Missing Correlation IDs

In a gateway or edge service, it’s common to generate a correlation ID if not already present:

String correlationId = Optional.ofNullable(MDC.get("X-Correlation-ID"))
                               .orElse(UUID.randomUUID().toString());

MDC.put("X-Correlation-ID", correlationId);

Then pass this into headers downstream.

Change content type / accept type

When consuming external or internal REST APIs, it's crucial to explicitly set Content-Type and Accept headers to align with what the server expects and returns. These headers define:

Content-Type: The format of the request body being sent.
Accept: The format that the client can process in the response.

Failing to set these correctly can lead to:

415 Unsupported Media Type
406 Not Acceptable
Unexpected deserialization failures

Typical Scenarios

Use Case

Required Content-Type

Required Accept-Type

Sending JSON payload

application/json

Consuming XML-based third-party API

application/xml

Posting form data

application/x-www-form-urlencoded

Depends on API, often JSON or text

Multipart file upload

multipart/form-data

Usually JSON or plain text

Consuming text or CSV file

text/plain, text/csv

1. Set Content-Type and Accept-Type Explicitly

We can customize both headers using HttpHeaders:

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));

MyRequest requestPayload = new MyRequest("sample", 42);
HttpEntity<MyRequest> requestEntity = new HttpEntity<>(requestPayload, headers);

ResponseEntity<MyResponse> response = restTemplate.exchange(
    "https://partner.api.com/process",
    HttpMethod.POST,
    requestEntity,
    MyResponse.class
);

2. Changing Content-Type for Form Submission

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
form.add("username", "john.doe");
form.add("password", "securePass");

HttpEntity<MultiValueMap<String, String>> entity = new HttpEntity<>(form, headers);

ResponseEntity<String> response = restTemplate.postForEntity(
    "https://auth.example.com/login",
    entity,
    String.class
);

3. Accepting XML Response from External Service

HttpHeaders headers = new HttpHeaders();
headers.setAccept(Collections.singletonList(MediaType.APPLICATION_XML));

HttpEntity<Void> entity = new HttpEntity<>(headers);

ResponseEntity<MyXmlResponse> response = restTemplate.exchange(
    "https://legacy.service.com/data.xml",
    HttpMethod.GET,
    entity,
    MyXmlResponse.class
);

Note: Our ObjectMapper (or JAXB if XML) must be correctly configured to handle XML.

4. Combine with Interceptors for Reusability

In large systems, we can create an interceptor that dynamically adjusts content negotiation based on context or configuration.

public class MediaTypeInterceptor implements ClientHttpRequestInterceptor {
    @Override
    public ClientHttpResponse intercept(HttpRequest request, byte[] body,
                                        ClientHttpRequestExecution execution) throws IOException {
        request.getHeaders().setContentType(MediaType.APPLICATION_JSON);
        request.getHeaders().setAccept(List.of(MediaType.APPLICATION_JSON));
        return execution.execute(request, body);
    }
}

@Bean
public RestTemplate restTemplate() {
    RestTemplate restTemplate = new RestTemplate();
    restTemplate.getInterceptors().add(new MediaTypeInterceptor());
    return restTemplate;
}

5. Accept Multiple Media Types

Sometimes, services support multiple response formats:

headers.setAccept(Arrays.asList(
    MediaType.APPLICATION_JSON,
    MediaType.APPLICATION_XML
));

This makes the request more flexible — the server can return what it prefers among those listed.

Reference: Required Dependencies & Import Statements

Maven Dependency

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Common Import Statements

Below are the commonly used import statements for the examples in this guide:

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.client.RestClientException;

import java.util.Base64;
import java.util.Map;
import java.util.Collections;

// For interceptors
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpRequest;
import org.springframework.http.client.ClientHttpResponse;

import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;

PreviousUsage NextHandling Responses

Last updated 3 days ago

About

Common Use Cases

Add Path and Query Param

1. Using Path Variables with URI Template Expansion

2. Path Params via UriComponentsBuilder for Dynamic URIs

3. Fully Programmatic Path + Query Construction

4. Mixing Path and Query Params in POST Request

Add Request Body

1. POST Request with JSON Body

2. PUT Request with Request Body

3. Exchange Method for Full Control (POST, PUT, PATCH)

4. Sending a List or Collection in Request Body

5. Sending a Form-Encoded Body (Non-JSON)

Add authentication headers

1. Bearer Token Authentication

2. Basic Authentication

3. API Key as Header

4. With Request Body and Auth Headers (POST)

5. Dynamically Inject Headers via Interceptor (Reusable)

Include trace/correlation IDs

1. Manually Add a Correlation ID to Headers

2. Automatically Inject Correlation ID via Interceptor

3. Integration with Spring Cloud Sleuth

4. Handling Missing Correlation IDs

Change content type / accept type

Typical Scenarios

1. Set Content-Type and Accept-Type Explicitly

2. Changing Content-Type for Form Submission

3. Accepting XML Response from External Service

4. Combine with Interceptors for Reusability

5. Accept Multiple Media Types

Reference: Required Dependencies & Import Statements

Maven Dependency

Common Import Statements

2. Path Params via `UriComponentsBuilder` for Dynamic URIs