API_Base
Class · Group: Web Services
Learn it: Web Services guide
global abstract inherited sharing class API_Base extends DML_TransactionExtends: 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
public class API_MyService extends API_Outbound
{
global override void configure()
{
super.configure();
requestPayload = new DTO_Request();
}
}Methods
| Method | Description |
|---|---|
| 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
global virtual void configure()Initializes global variables and timers. Override this method to configure DTOs, mock types, timeouts, and other service-specific settings.
Example
global override void configure()
{
super.configure();
requestPayload = new DTO_Request();
responsePayload = new DTO_Response();
defaultMockBody = '{"success": true}';
}getBody
global virtual String getBody()Returns the HTTP request body.
Returns String — String The request body, empty by default.
Example
global override String getBody()
{
return requestPayload.serialize();
}getEncoding
global abstract String getEncoding()Returns the HTTP character encoding.
Returns String — String The encoding scheme, must be implemented by subclasses.
Example
global override String getEncoding()
{
return 'application/xml';
}getHttpMethod
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
global override HttpMethod getHttpMethod()
{
return HttpMethod.GET;
}getValidationErrors
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
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
global virtual void handleError(Exception exceptionThrown)Handles errors encountered during the service call.
Parameters
| Parameter | Type | Description |
|---|---|---|
exceptionThrown | Exception | The exception to handle. |
Example
global override void handleError(Exception exceptionThrown)
{
super.handleError(exceptionThrown);
// custom error handling
}isDisabled
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
global override Boolean isDisabled()
{
return super.isDisabled() || customDisableCheck();
}onDMLFinished
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
global override void onDMLFinished()
{
super.onDMLFinished();
// your own work, after the commit has written its records
}onSuccess
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
global override void onSuccess()
{
super.onSuccess();
doUpdate(updatedRecord);
}Properties
| Property | Description |
|---|---|
| global ApiCall__c apiCall | The ApiCall__c object that initiated the service call. |
| global String correlationId | The unique correlation ID for this handler instance. |
| global String errorText | Returns errors encountered during the request or the error payload if no error is logged. |
| global DTO_NameValues inputs | DTO containing parameters passed to the API. |
| global API_Base.ServiceCallResult result | Tracks the request, response, and status of a web service call. |
| global ApiSetting__mdt setting | API settings metadata for this service, lazy-loaded from ApiSetting__mdt. |
apiCall
global ApiCall__c apiCallType: 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
global String correlationIdType: String
The unique correlation ID for this handler instance.
errorText
global String errorTextType: String
Returns errors encountered during the request or the error payload if no error is logged.
inputs
global DTO_NameValues inputsType: DTO_NameValues
DTO containing parameters passed to the API.
result
global API_Base.ServiceCallResult resultType: API_Base.ServiceCallResult
Tracks the request, response, and status of a web service call.
setting
global ApiSetting__mdt settingType: ApiSetting__mdt
API settings metadata for this service, lazy-loaded from ApiSetting__mdt.
Inner Classes
| Class | Description |
|---|---|
| HttpMethod | HTTP method verbs for web service calls. |
| ServiceCallResult | Tracks the request, response, and status of a web service call. |
| WebserviceStatus | Enum representing the status of a web service call. |