UTIL_HttpClient.RequestBuilder

Class

global inherited sharing class UTIL_HttpClient.RequestBuilder

Fluent builder for configuring and executing HTTP requests through API_Dispatcher.

Example

Map<String, Object> result = UTIL_HttpClient.get('MyService', '/status')
   .header('X-Custom', 'value')
   .timeout(30000)
   .asMap();

---

Methods

Method	Description
global Map<String, Object> asMap()	Executes the request and deserializes the response body as an untyped Map.
global String asString()	Executes the request and returns the response body as a String.
global UTIL_HttpClient.RequestBuilder body(Object requestBody)	Sets the request body by JSON-serializing the provided object.
global UTIL_HttpClient.RequestBuilder body(String requestBody)	Sets the request body as a raw string.
global UTIL_HttpClient.RequestBuilder credential(String credential)	Sets the Named Credential for the endpoint.
global Object deserialize(Type responseType)	Executes the request and deserializes the response body into the specified type.
global UTIL_HttpClient.RequestBuilder header(String name, String value)	Adds a single header to the request.
global UTIL_HttpClient.RequestBuilder headers(Map<String, String> headerMap)	Adds multiple headers to the request.
global API_Outbound invoke()	Executes in delegation mode and returns the delegate handler instance.
global UTIL_HttpClient.RequestBuilder method(API_Base.HttpMethod httpMethod)	Sets the HTTP method for the request.
global UTIL_HttpClient.RequestBuilder onFailure(UTIL_HttpClient.FailureAction action)	Sets the failure handling strategy.
global UTIL_HttpClient.RequestBuilder path(String urlPath)	Sets the URL path for the request.
global UTIL_HttpClient.RequestBuilder pathParam(String name, String value)	Replaces a {name} placeholder in the URL path with a value.
global UTIL_HttpClient.RequestBuilder queryParam(String name, String value)	Adds a query parameter to the request URL.
global UTIL_HttpClient.RequestBuilder replaceRequestToken(String searchToken, String replaceToken)	Registers a single request body replacement token.
global UTIL_HttpClient.RequestBuilder replaceRequestTokens(Map<String, String> tokens)	Registers multiple request body replacement tokens.
global UTIL_HttpClient.RequestBuilder replaceResponseToken(String searchToken, String replaceToken)	Registers a single response body replacement token.
global UTIL_HttpClient.RequestBuilder replaceResponseTokens(Map<String, String> tokens)	Registers multiple response body replacement tokens.
global UTIL_HttpClient.RequestBuilder retryOn(Set<Integer> statusCodes)	Restricts retry to specific HTTP status codes.
global HttpResponse send()	Executes the HTTP request and returns the raw HttpResponse.
global UTIL_HttpClient.RequestBuilder skipLogging()	Skips ApiCall__c persistence for this request.
global UTIL_HttpClient.RequestBuilder timeout(Integer milliseconds)	Sets the request timeout in milliseconds.
global UTIL_HttpClient.RequestBuilder withCircuitBreaker()	Enables circuit breaker protection using the credential name as identifier.
global UTIL_HttpClient.RequestBuilder withCircuitBreaker(String circuitName)	Enables circuit breaker protection with a custom identifier.
global UTIL_HttpClient.RequestBuilder withCorrelationId(String correlationId)	Sets a correlation ID for cross-transaction log tracing.
global UTIL_HttpClient.RequestBuilder withExponentialBackoff(Integer maxRetries, Integer baseBackoffSeconds)	Enables synchronous retry with exponential backoff.
global UTIL_HttpClient.RequestBuilder withIdempotencyKey(String idempotencyKey)	Sets an explicit idempotency key for duplicate detection.
global UTIL_HttpClient.RequestBuilder withMockResponse(API_MockFactory.MockResponse mockResponse)	Sets a mock response to inject at framework level, overriding the handler's own mock.
global UTIL_HttpClient.RequestBuilder withParameter(String name, String value)	Adds a request parameter for subscriber handler mode.
global UTIL_HttpClient.RequestBuilder withParameters(Map<String, String> parameters)	Adds multiple request parameters for subscriber handler mode.
global UTIL_HttpClient.RequestBuilder withRetry(Integer maxRetries)	Enables synchronous retry with the specified maximum attempts.
global UTIL_HttpClient.RequestBuilder withRetry(Integer maxRetries, Integer backoffSeconds)	Enables synchronous retry with a linear backoff.
global UTIL_HttpClient.RequestBuilder withTriggeringRecord(Id recordId)	Links this callout to a triggering business record.

asMap

global Map<String, Object> asMap()

Executes the request and deserializes the response body as an untyped Map.

Returns Object — The deserialized response as Map of String to Object

Example

Map<String, Object> data = UTIL_HttpClient.get('MyService', '/data').asMap();

asString

global String asString()

Executes the request and returns the response body as a String.

Returns String — The response body string

Example

String body = UTIL_HttpClient.get('MyService', '/data').asString();

body

global UTIL_HttpClient.RequestBuilder body(Object requestBody)

Sets the request body by JSON-serializing the provided object.

Parameters

Parameter	Type	Description
requestBody	Object	The object to serialize as JSON

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .body(new Map<String, String>{'key' => 'value'})
   .send();

global UTIL_HttpClient.RequestBuilder body(String requestBody)

Sets the request body as a raw string.

Parameters

Parameter	Type	Description
requestBody	String	The raw body string

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .body('{"key": "value"}')
   .send();

credential

global UTIL_HttpClient.RequestBuilder credential(String credential)

Sets the Named Credential for the endpoint.

Parameters

Parameter	Type	Description
credential	String	The Named Credential name

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.useHandler(API_SendEmail.class)
   .credential('EmailGateway')
   .invoke();

deserialize

global Object deserialize(Type responseType)

Executes the request and deserializes the response body into the specified type.

Parameters

Parameter	Type	Description
responseType	Type	The Apex Type to deserialize into

Returns Object — The deserialized response object

Example

MyDTO result = (MyDTO)UTIL_HttpClient.get('MyService', '/data')
   .deserialize(MyDTO.class);

header

global UTIL_HttpClient.RequestBuilder header(String name, String value)

Adds a single header to the request.

Parameters

Parameter	Type	Description
name	String	The header name
value	String	The header value

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .header('X-Custom', 'value')
   .send();

headers

global UTIL_HttpClient.RequestBuilder headers(Map<String, String> headerMap)

Adds multiple headers to the request.

Parameters

Parameter	Type	Description
headerMap	Map	Map of header names to values

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .headers(new Map<String, String>{'X-Custom' => 'value', 'X-Trace' => 'abc'})
   .send();

invoke

global API_Outbound invoke()

Executes in delegation mode and returns the delegate handler instance.

Returns API_Outbound — The executed API_Outbound delegate handler

Example

API_Outbound handler = UTIL_HttpClient.useHandler(API_SendEmail.class)
   .withTriggeringRecord(recordId)
   .invoke();
API_SendEmail.DTO_Response dto = (API_SendEmail.DTO_Response)handler.responsePayload;

method

global UTIL_HttpClient.RequestBuilder method(API_Base.HttpMethod httpMethod)

Sets the HTTP method for the request.

Parameters

Parameter	Type	Description
httpMethod	API_Base.HttpMethod	The HTTP method enum value

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/data')
   .method(API_Base.HttpMethod.PUT)
   .send();

onFailure

global UTIL_HttpClient.RequestBuilder onFailure(UTIL_HttpClient.FailureAction action)

Sets the failure handling strategy.

Parameters

Parameter	Type	Description
action	UTIL_HttpClient.FailureAction	The failure action to apply

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .onFailure(UTIL_HttpClient.FailureAction.LOG_FAILURE)
   .send();

path

global UTIL_HttpClient.RequestBuilder path(String urlPath)

Sets the URL path for the request.

Parameters

Parameter	Type	Description
urlPath	String	The URL path to append

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/api')
   .path('/v2/send')
   .send();

pathParam

global UTIL_HttpClient.RequestBuilder pathParam(String name, String value)

Replaces a {name} placeholder in the URL path with a value.

Parameters

Parameter	Type	Description
name	String	The placeholder name (without braces)
value	String	The replacement value

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.get('CRM', '/accounts/{id}')
   .pathParam('id', accountId)
   .send();

queryParam

global UTIL_HttpClient.RequestBuilder queryParam(String name, String value)

Adds a query parameter to the request URL.

Parameters

Parameter	Type	Description
name	String	The parameter name
value	String	The parameter value

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.get('MyService', '/search')
   .queryParam('q', 'test')
   .queryParam('limit', '10')
   .send();

replaceRequestToken

global UTIL_HttpClient.RequestBuilder replaceRequestToken(String searchToken, String replaceToken)

Registers a single request body replacement token. The search token in the serialized request body will be replaced with the replace token before sending.

Parameters

Parameter	Type	Description
searchToken	String	The token to search for in the request body
replaceToken	String	The token to replace it with

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('PaymentGateway', '/charges')
   .body(chargeRequest)
   .replaceRequestToken('currencyIsoCode', 'currency')
   .send();

replaceRequestTokens

global UTIL_HttpClient.RequestBuilder replaceRequestTokens(Map<String, String> tokens)

Registers multiple request body replacement tokens. Each search token in the serialized request body will be replaced with its corresponding replace token before sending.

Parameters

Parameter	Type	Description
tokens	Map	Map of search tokens to their replacement values

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('PaymentGateway', '/charges')
   .body(chargeRequest)
   .replaceRequestTokens(new Map<String, String>{'currencyIsoCode' => 'currency', 'groupName' => 'group'})
   .send();

replaceResponseToken

global UTIL_HttpClient.RequestBuilder replaceResponseToken(String searchToken, String replaceToken)

Registers a single response body replacement token. The search token in the response body will be replaced with the replace token after receiving.

Parameters

Parameter	Type	Description
searchToken	String	The token to search for in the response body
replaceToken	String	The token to replace it with

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

HttpResponse response = UTIL_HttpClient.get('PaymentGateway', '/charges')
   .replaceResponseToken('currency', 'currencyIsoCode')
   .send();

replaceResponseTokens

global UTIL_HttpClient.RequestBuilder replaceResponseTokens(Map<String, String> tokens)

Registers multiple response body replacement tokens. Each search token in the response body will be replaced with its corresponding replace token after receiving.

Parameters

Parameter	Type	Description
tokens	Map	Map of search tokens to their replacement values

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

HttpResponse response = UTIL_HttpClient.get('PaymentGateway', '/charges')
   .replaceResponseTokens(new Map<String, String>{'currency' => 'currencyIsoCode', 'group' => 'groupName'})
   .send();

retryOn

global UTIL_HttpClient.RequestBuilder retryOn(Set<Integer> statusCodes)

Restricts retry to specific HTTP status codes.

Parameters

Parameter	Type	Description
statusCodes	Set	The status codes eligible for retry

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .withRetry(3)
   .retryOn(new Set<Integer>{500, 503})
   .send();

send

global HttpResponse send()

Executes the HTTP request and returns the raw HttpResponse.

Returns HttpResponse — The HttpResponse from the callout

Example

HttpResponse response = UTIL_HttpClient.get('MyService', '/data').send();

skipLogging

global UTIL_HttpClient.RequestBuilder skipLogging()

Skips ApiCall__c persistence for this request.

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.get('MyService', '/healthCheck')
   .skipLogging()
   .send();

timeout

global UTIL_HttpClient.RequestBuilder timeout(Integer milliseconds)

Sets the request timeout in milliseconds.

Parameters

Parameter	Type	Description
milliseconds	Integer	The timeout value

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.get('MyService', '/data')
   .timeout(30000)
   .send();

withCircuitBreaker

global UTIL_HttpClient.RequestBuilder withCircuitBreaker()

Enables circuit breaker protection using the credential name as identifier.

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .withCircuitBreaker()
   .send();

global UTIL_HttpClient.RequestBuilder withCircuitBreaker(String circuitName)

Enables circuit breaker protection with a custom identifier.

Parameters

Parameter	Type	Description
circuitName	String	The circuit breaker identifier

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .withCircuitBreaker('payment-gateway')
   .send();

withCorrelationId

global UTIL_HttpClient.RequestBuilder withCorrelationId(String correlationId)

Sets a correlation ID for cross-transaction log tracing.

Parameters

Parameter	Type	Description
correlationId	String	The correlation identifier

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .withCorrelationId('txn-12345')
   .send();

withExponentialBackoff

global UTIL_HttpClient.RequestBuilder withExponentialBackoff(Integer maxRetries, Integer baseBackoffSeconds)

Enables synchronous retry with exponential backoff.

Parameters

Parameter	Type	Description
maxRetries	Integer	The maximum number of retry attempts
baseBackoffSeconds	Integer	The base backoff period in seconds

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .withExponentialBackoff(3, 2)
   .send();

withIdempotencyKey

global UTIL_HttpClient.RequestBuilder withIdempotencyKey(String idempotencyKey)

Sets an explicit idempotency key for duplicate detection. When set, this key takes priority over auto-generated keys.

Parameters

Parameter	Type	Description
idempotencyKey	String	The idempotency key value

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('PaymentGateway', '/charges')
   .body(chargeRequest)
   .withIdempotencyKey('order-12345')
   .send();

withMockResponse

global UTIL_HttpClient.RequestBuilder withMockResponse(API_MockFactory.MockResponse mockResponse)

Sets a mock response to inject at framework level, overriding the handler's own mock.

Parameters

Parameter	Type	Description
mockResponse	API_MockFactory.MockResponse	The mock response to inject

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

API_MockFactory.MockResponse mock = new API_MockFactory.MockResponse();
mock.body = '{"id": "12345"}';
UTIL_HttpClient.post('MyService', '/send')
   .withMockResponse(mock)
   .send();

withParameter

global UTIL_HttpClient.RequestBuilder withParameter(String name, String value)

Adds a request parameter for subscriber handler mode.

Parameters

Parameter	Type	Description
name	String	The parameter name
value	String	The parameter value

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.useHandler(API_SendEmail.class)
   .withParameter(API_SendEmail.PARAM_SUBJECT, 'Hello')
   .invoke();

withParameters

global UTIL_HttpClient.RequestBuilder withParameters(Map<String, String> parameters)

Adds multiple request parameters for subscriber handler mode.

Parameters

Parameter	Type	Description
parameters	Map	Map of parameter names to values

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

Map<String, String> parameters = new Map<String, String>{'key' => 'value'};
UTIL_HttpClient.useHandler(API_SendEmail.class)
   .withParameters(parameters)
   .invoke();

withRetry

global UTIL_HttpClient.RequestBuilder withRetry(Integer maxRetries)

Enables synchronous retry with the specified maximum attempts.

Parameters

Parameter	Type	Description
maxRetries	Integer	The maximum number of retry attempts

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .withRetry(3)
   .send();

global UTIL_HttpClient.RequestBuilder withRetry(Integer maxRetries, Integer backoffSeconds)

Enables synchronous retry with a linear backoff.

Parameters

Parameter	Type	Description
maxRetries	Integer	The maximum number of retry attempts
backoffSeconds	Integer	The backoff period in seconds

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .withRetry(3, 5)
   .send();

withTriggeringRecord

global UTIL_HttpClient.RequestBuilder withTriggeringRecord(Id recordId)

Links this callout to a triggering business record.

Parameters

Parameter	Type	Description
recordId	Id	The Salesforce record Id

Returns UTIL_HttpClient.RequestBuilder — This builder for method chaining

Example

UTIL_HttpClient.post('MyService', '/send')
   .withTriggeringRecord(record.Id)
   .send();