KernDX

Appearance

API_Outbound ​

Class · Group: Web Services

apex
global virtual inherited sharing class API_Outbound extends API_Base

Extends: API_Base

Known Derived Types: API_CallCurrentOrg

Base class for all outbound web service calls. Extends API_Base to provide functionality for making HTTP callouts, handling responses, managing retries, and token replacements.

Since: 1.0

Example:

apex
public with sharing class API_SendEmail extends API_Outbound
{
    public override void configure()
    {
        super.configure();
        requestPayload = new DTO_Request();
        responsePayload = new DTO_Response();
        defaultMockBody = '{"messageId": "msg-12345"}';
    }
}

Properties ​

PropertyDescription
global String baseUrlReturns the base URL of the web service.
global String defaultMockBodyDefault mock response body for unit tests and mock mode.
global HttpRequest requestThe request object used by the API handler to make an outbound call.
global DTO_Base requestPayloadThe DTO that should be serialized for the request body in outbound service calls.
global HttpResponse responseThe response object containing the results of the HTTP callout.
global DTO_Base responsePayloadThe DTO that will deserialize the response body of the external web service call.

Fields ​

FieldDescription
global Boolean requiresTriggeringRecordWhether this service requires a triggering object ID.

Methods ​

MethodDescription
global override virtual void configure()Initializes global variables; override in descendant classes if needed.
global virtual HttpRequest createRequest(String requestBody)Constructs the HttpRequest object used to make the outbound API call.
global virtual UTIL_Retry.Strategy createRetryStrategy()Creates the retry strategy for failed service calls.
global virtual String getAuthorisationToken()Returns the authorization token required for outbound API requests.
global virtual override String getBody()Generates the request body using the type of the requestPayload.
global override virtual String getEncoding()Retrieves the HTTP encoding.
global override virtual API_Base.HttpMethod getHttpMethod()Retrieves the HTTP method used for making the outbound request.
global virtual String getQueryParameters()Retrieves relevant query parameters.
global virtual void getRequestReplacementTokens(List<List<String> replaceTokens)Specifies token replacements for the request body before serialization.
global virtual Set getRequiredInputs()Indicates required service inputs.
global virtual String getResponseBody()Retrieves the current response body; override to manipulate response body first.
global virtual void getResponseReplacementTokens(List<List<String> replaceTokens)Specifies token replacements for the response body before deserialization.
global virtual Integer getTimeout()Retrieves the HTTP Service Timeout.
global virtual String getWebServiceEndPoint()Constructs and returns the full URL endpoint for the web service, resolving Named Credentials and appending the API path.
global virtual Boolean hasArrayResponse()Checks if the JSON response is in the form of an array without a key.
global override Boolean isDisabled()Checks whether the API has been disabled for the current user by verifying custom settings or feature switches.
global virtual void parseResponse()Called if request is successful; override to consume response.
global virtual void prepareRequest()Prepares the outbound request by querying Salesforce data and populating the request DTO.
global virtual void setHeaders()Sets the HTTP headers for the request.

Property Details ​

baseUrl ​

apex
global String baseUrl

Type: String

Returns the base URL of the web service. This resolves Named Credentials to handle secure credential management in Salesforce.

Since:

Example:

defaultMockBody ​

apex
global String defaultMockBody

Type: String

Default mock response body for unit tests and mock mode. Set this in configure() to declare the handler's default mock response. When set, API_MockFactory.CalloutMock uses this as fallback when no factory mock is registered.

Since:

Example:

request ​

apex
@TestVisible global HttpRequest request

Type: HttpRequest

The request object used by the API handler to make an outbound call. The HttpRequest object is initialized lazily when it's first accessed.

Since:

Example:

See Also: HttpRequest

requestPayload ​

apex
global DTO_Base requestPayload

Type: DTO_Base

The DTO that should be serialized for the request body in outbound service calls. This object contains the data that will be sent to the external service as part of the HTTP request.

Since:

Example:

response ​

apex
@TestVisible global HttpResponse response

Type: HttpResponse

The response object containing the results of the HTTP callout. This object is populated after the HTTP call is executed.

Since:

Example:

See Also: HttpResponse

responsePayload ​

apex
@TestVisible global DTO_Base responsePayload

Type: DTO_Base

The DTO that will deserialize the response body of the external web service call. This object will be populated with the response data after the HTTP call completes.

Since:

Example:

Method Details ​

configure ​

apex
global override virtual void configure()

Initializes global variables; override in descendant classes if needed.

Since: 1.0

Example:

apex
global override void configure()
{
    super.configure();
    requestPayload = new DTO_Request();
    responsePayload = new DTO_Response();
    defaultMockBody = '{"messageId": "msg-12345"}';
}

createRequest ​

apex
global virtual HttpRequest createRequest(String requestBody)

Constructs the HttpRequest object used to make the outbound API call. It sets the headers, request body, and endpoint URL.

Parameters:

  • requestBody (String) - The body content of the request.

Returns: HttpRequest - The fully configured request object.

Since: 1.0

Example:

apex
global override HttpRequest createRequest(String requestBody)
{
    HttpRequest httpRequest = super.createRequest(requestBody);
    // customize request
    return httpRequest;
}

createRetryStrategy ​

apex
global virtual UTIL_Retry.Strategy createRetryStrategy()

Creates the retry strategy for failed service calls. Override this method in subclasses to provide custom retry strategies.

Returns: UTIL_Retry.Strategy - Configured instance

Since: 1.0

Example:

apex
global class API_PaymentGateway extends API_Outbound
{
    global override UTIL_Retry.Strategy createRetryStrategy()
    {
        return UTIL_Retry.exponential()
            .withBaseBackoff(5)
            .withMaxRetries(3);
    }
}

getAuthorisationToken ​

apex
global virtual String getAuthorisationToken()

Returns the authorization token required for outbound API requests.

Returns: String - The authorization token to be used in the Authorization HTTP header.

Since: 1.0

Example:

apex
global override String getAuthorisationToken()
{
    return 'Bearer ' + accessToken;
}

getBody ​

apex
global virtual override String getBody()

Generates the request body using the type of the requestPayload. Applies token replacements to the request body before sending.

Returns: String - The serialized request body.

Since: 1.0

Example:

apex
global override String getBody()
{
    return JSON.serialize(customPayload);
}

See Also: DTO_Base

getEncoding ​

apex
global override virtual String getEncoding()

Retrieves the HTTP encoding.

Returns: String - The HTTP encoding, defaults to JSON.

Since: 1.0

Example:

apex
global override String getEncoding()
{
    return 'application/xml';
}

getHttpMethod ​

apex
global override virtual API_Base.HttpMethod getHttpMethod()

Retrieves the HTTP method used for making the outbound request.

Returns: API_Base.HttpMethod - The HTTP method to be used. Defaults to POST if not provided by the superclass.

Since: 1.0

Example:

apex
global override HttpMethod getHttpMethod()
{
    return HttpMethod.GET;
}

getQueryParameters ​

apex
global virtual String getQueryParameters()

Retrieves relevant query parameters.

Returns: String - A list of query parameters.

Since: 1.0

Example:

apex
global override String getQueryParameters()
{
    return 'key=' + EncodingUtil.urlEncode(value, 'UTF-8');
}

getRequestReplacementTokens ​

apex
global virtual void getRequestReplacementTokens(List<String> searchTokens, List<String> replaceTokens)

Specifies token replacements for the request body before serialization. Override to replace reserved words or tokens in the request body before sending.

Parameters:

  • searchTokens (List) - The list of search tokens to look for in the request body.
  • replaceTokens (String) - The list of replacement tokens to use if matching search tokens are found.

Since: 1.0

Example:

apex
global override void getRequestReplacementTokens(List<String> searchTokens, List<String> replaceTokens)
{
    searchTokens.add('{TODAY}');
    replaceTokens.add(String.valueOf(Date.today()));
}

getRequiredInputs ​

apex
global virtual Set<String> getRequiredInputs()

Indicates required service inputs.

Returns: String - A set of required service input names.

Since: 1.0

Example:

apex
global override Set<String> getRequiredInputs()
{
    Set<String> requiredInputs = super.getRequiredInputs();
    requiredInputs.add(PARAM_RECIPIENT);
    return requiredInputs;
}

getResponseBody ​

apex
global virtual String getResponseBody()

Retrieves the current response body; override to manipulate response body first. Automatically wraps array responses and applies token replacements.

Returns: String - The response that will be parsed.

Since: 1.0

Example:

apex
global override String getResponseBody()
{
    String body = super.getResponseBody();
    // manipulate response body before parsing
    return body;
}

getResponseReplacementTokens ​

apex
global virtual void getResponseReplacementTokens(List<String> searchTokens, List<String> replaceTokens)

Specifies token replacements for the response body before deserialization. Override to replace reserved words or tokens in the response before processing.

Parameters:

  • searchTokens (List) - The list of search tokens to look for in the response body.
  • replaceTokens (String) - The list of replacement tokens to use if matching search tokens are found.

Since: 1.0

Example:

apex
global override void getResponseReplacementTokens(List<String> searchTokens, List<String> replaceTokens)
{
    searchTokens.add('currency');
    replaceTokens.add('currencyIsoCode');
}

getTimeout ​

apex
global virtual Integer getTimeout()

Retrieves the HTTP Service Timeout.

Returns: Integer - The timeout value in milliseconds, defaults to 120000.

Since: 1.0

Example:

apex
global override Integer getTimeout()
{
    return 60000;
}

getWebServiceEndPoint ​

apex
global virtual String getWebServiceEndPoint()

Constructs and returns the full URL endpoint for the web service, resolving Named Credentials and appending the API path.

Returns: String - The full URL endpoint for the web service.

Since: 1.0

Example:

apex
global override String getWebServiceEndPoint()
{
    return super.getWebServiceEndPoint() + '/custom-path';
}

hasArrayResponse ​

apex
global virtual Boolean hasArrayResponse()

Checks if the JSON response is in the form of an array without a key. Salesforce DTO classes cannot parse arrays directly, so this method helps handle responses that are arrays.

Returns: Boolean - Boolean indicating if the response is an array.

Since: 1.0

Example:

apex
global override Boolean hasArrayResponse()
{
    return true;
}

isDisabled ​

apex
global override Boolean isDisabled()

Checks whether the API has been disabled for the current user by verifying custom settings or feature switches.

Returns: Boolean - True if the API is disabled, false otherwise.

Since: 1.0

Example:

apex
global override Boolean isDisabled()
{
    return super.isDisabled() || customDisableCheck();
}

parseResponse ​

apex
global virtual void parseResponse()

Called if request is successful; override to consume response.

Since: 1.0

Example:

apex
global override void parseResponse()
{
    super.parseResponse();
    DTO_Response dto = (DTO_Response)responsePayload;
    // process the response
}

prepareRequest ​

apex
global virtual void prepareRequest()

Prepares the outbound request by querying Salesforce data and populating the request DTO.

Since: 1.0

Example:

apex
global override void prepareRequest()
{
    super.prepareRequest();
    // additional request preparation
}

setHeaders ​

apex
global virtual void setHeaders()

Sets the HTTP headers for the request. Includes Accept header for JSON responses. Override in child classes to add additional service-specific headers.

Since: 1.0

Example:

apex
global override void setHeaders()
{
    super.setHeaders();
    request.setHeader('Custom-Header', 'CustomValue');
}

Field Details ​

requiresTriggeringRecord ​

apex
global Boolean requiresTriggeringRecord

Type: Boolean

Whether this service requires a triggering object ID. Override in configure() to set to false for services that don't require a triggering record.

Since: 1.0

Example:

apex
global override void configure()
{
    super.configure();
    requiresTriggeringRecord = false;
}