Skip to content

API_Base ​

Class · Group: Web Services

Learn it: Web Services guide

apex
global abstract inherited sharing class API_Base extends DML_Transaction

Extends: DML_Transaction

Known Derived Types: API_CallCurrentOrg, API_Inbound, API_Outbound

Base class for all API web service calls (outbound and inbound). Provides common functionality for HTTP request handling, error management, and data persistence.

Example

apex
public class API_MyService extends API_Outbound
{
    global override void configure()
    {
        super.configure();
        requestPayload = new DTO_Request();
    }
}

Methods ​

MethodDescription
global virtual void configure()Initializes global variables and timers.
global virtual String getBody()Returns the HTTP request body.
global abstract String getEncoding()Returns the HTTP character encoding.
global virtual API_Base.HttpMethod getHttpMethod()Returns the HTTP method for the service.
global virtual List<String> getValidationErrors()Determines if the web service request should be aborted.
global virtual void handleError(Exception exceptionThrown)Handles errors encountered during the service call.
global virtual Boolean isDisabled()Checks if the API is disabled for the current user.
global override virtual void onDMLFinished()Runs after the commit has written its records to the database, and before onCommitWorkFinishing and onCommitWorkFinished.
global virtual void onSuccess()Registers database changes after a successful call.

configure ​

apex
global virtual void configure()

Initializes global variables and timers. Override this method to configure DTOs, mock types, timeouts, and other service-specific settings.

Example

apex
global override void configure()
{
    super.configure();
    requestPayload = new DTO_Request();
    responsePayload = new DTO_Response();
    defaultMockBody = '{"success": true}';
}

getBody ​

apex
global virtual String getBody()

Returns the HTTP request body.

Returns String — String The request body, empty by default.

Example

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

getEncoding ​

apex
global abstract String getEncoding()

Returns the HTTP character encoding.

Returns String — String The encoding scheme, must be implemented by subclasses.

Example

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

getHttpMethod ​

apex
global virtual API_Base.HttpMethod getHttpMethod()

Returns the HTTP method for the service.

Returns API_Base.HttpMethod — The HTTP method enum value, or null by default.

Example

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

getValidationErrors ​

apex
global virtual List<String> getValidationErrors()

Determines if the web service request should be aborted. Returns a list of validation error messages. Override this to add your own validation. Framework validation is handled internally by performValidation() — no super call needed.

Returns String — A list of error messages. Empty list means validation passed.

Example

apex
global override List<String> getValidationErrors()
{
    List<String> errors = new List<String>();
    if(String.isBlank(apiCall.TriggeringRecordId__c))
    {
        errors.add('Triggering record is required');
    }
    return errors;
}

handleError ​

apex
global virtual void handleError(Exception exceptionThrown)

Handles errors encountered during the service call.

Parameters

ParameterTypeDescription
exceptionThrownExceptionThe exception to handle.

Example

apex
global override void handleError(Exception exceptionThrown)
{
    super.handleError(exceptionThrown);
    // custom error handling
}

isDisabled ​

apex
global virtual Boolean isDisabled()

Checks if the API is disabled for the current user. Override to add custom disable logic.

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

Example

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

onDMLFinished ​

apex
global override virtual void onDMLFinished()

Runs after the commit has written its records to the database, and before onCommitWorkFinishing and onCommitWorkFinished. It keeps a copy of the call record's field values as they were written. The call record is saved once more after the commit, to write the timings and the outcome. Because of the copy, that second save sends only the fields that changed after the commit, such as the response the inbound commit writes in onCommitWorkFinishing. When an attempt fails after this point, the copy is dropped again. Your handler class may override this method. Your override must call super.onDMLFinished() first. If it does not, the second save sends the whole call record again.

Example

apex
global override void onDMLFinished()
{
    super.onDMLFinished();
    // your own work, after the commit has written its records
}

onSuccess ​

apex
global virtual void onSuccess()

Registers database changes after a successful call. Records you register here are saved in system mode, so the running user's object and field permissions are not checked. To save with the user's permissions, use DML_Builder.newTransaction().withUserMode() in its own transaction.

Example

apex
global override void onSuccess()
{
    super.onSuccess();
    doUpdate(updatedRecord);
}

Properties ​

PropertyDescription
global ApiCall__c apiCallThe ApiCall__c object that initiated the service call.
global String correlationIdThe unique correlation ID for this handler instance.
global String errorTextReturns errors encountered during the request or the error payload if no error is logged.
global DTO_NameValues inputsDTO containing parameters passed to the API.
global API_Base.ServiceCallResult resultTracks the request, response, and status of a web service call.
global ApiSetting__mdt settingAPI settings metadata for this service, lazy-loaded from ApiSetting__mdt.

apiCall ​

apex
global ApiCall__c apiCall

Type: ApiCall__c

The ApiCall__c object that initiated the service call.

Its payload fields (the request, the response, the address and the request parameters) are not always masked, even after the call was saved. A payload that fits its field is masked when the call is saved to the database, but this record still holds the raw text the call sent or received: the save does not copy the masked text back into it. A payload field holds masked text only when the payload is longer than the field (the masked text is then cut to fit), or, in some cases, when the payload was masked again to make its file. So code that reads this record after a save must never pass a payload field on as if it were masked. To get the masked text, read the saved call back from the database by its Id.

correlationId ​

apex
global String correlationId

Type: String

The unique correlation ID for this handler instance.

errorText ​

apex
global String errorText

Type: String

Returns errors encountered during the request or the error payload if no error is logged.

inputs ​

apex
global DTO_NameValues inputs

Type: DTO_NameValues

DTO containing parameters passed to the API.

result ​

apex
global API_Base.ServiceCallResult result

Type: API_Base.ServiceCallResult

Tracks the request, response, and status of a web service call.

setting ​

apex
global ApiSetting__mdt setting

Type: ApiSetting__mdt

API settings metadata for this service, lazy-loaded from ApiSetting__mdt.

Inner Classes ​

ClassDescription
HttpMethodHTTP method verbs for web service calls.
ServiceCallResultTracks the request, response, and status of a web service call.
WebserviceStatusEnum representing the status of a web service call.