External Service Registrations in Apex

External Service

The external service registration with name ServiceName is the Apex class ExternalService.ServiceName making the external service callable in Apex. To call operations on the external service in Apex, instantiate an instance with the default constructor.

For example, create an instance of CreditScore to make callouts:

ExternalService.CreditScore creditScore = new ExternalService.CreditScore();

External Service Operation

A registered external service’s derived operation name is declared as an Apex method on the Apex external service class.

• The operation input parameters are declared in the method’s request class in the order of declaration in the external service’s specification and the corresponding parameter data type in Apex.
• The operation output parameters with successful HTTP response codes are declared in the method’s return response class. The API specification’s HTTP response codes are declared in the response class. The response class’ property ResponseCode captures the callout’s HTTP response code value.
• The operation output parameters with HTTP error response codes are declared in the method’s exception class for HTTP error codes. The API specification’s HTTP error response codes are declared in the response exception class. The property ResponseCode captures the callout’s HTTP error response code value. The property DefaultResponse the operation’s default response message value for non declared HTTP response codes.

For example, the CreditScore’s operation getAccountLastCreditRating is declared as Apex method on the Apex class ExternalService.CreditScore with corresponding input arguments, return response type and exception object:

global class CreditScore {
     global getAccountLastCreditRating_Response getAccountLastCreditRating(
        getAccountLastCreditRating_Request input) {...}

    global class getAccountLastCreditRating_Request {
        global accountId accountId {get; set;}
    }
    
    global class getAccountLastCreditRating_Response {
        global Integer ResponseCode {get; set;}
        CreditScore_creditRating Code200 {get; set}
    }
        
    global class getAccountLastCreditRating_ResponseException {
        global Integer ResponseCode {get; set;}
        global String DefaultResponse {get; set;}
        global String Code405 {get; set;}    
    }
}

In the example, the method getAccountLastCreditRating throws exception getAccountLastCreditRating_ResponseException that you can catch to process HTTP error codes.

To get the account’s last credit rating in Apex:

public class CreditScoreRater {
    // Application domain exception
    public class CreditScoreException extends Exception {}

    public String rateCreditScore(String accountIdentifier) {
        ExternalService.CreditScore creditScore = new ExternalService.CreditScore();
        
        // Set the account ID
        ExternalService.CreditScore_accountId accountId = 
            new ExternalService.CreditScore_accountId();
        accountId.accountIdString = accountIdentifier;
        
        // Call to get the last credit rating
        try {
            // Construct the request
            ExternalService.CreditScore.getAccountLastCreditRating_Request request =
                new ExternalService.CreditScore.getAccountLastCreditRating_Request();
            // Set the request input parameters: The request body
            request.body = accountId;
            
            // Call the external credit rating service
            ExternalService.CreditScore.getAccountLastCreditRating_Response response =  
               creditScore.getAccountLastCreditRating(request);
               
            // Get the credit rating response for HTTP status code 200           
            ExternalService.CreditScore_creditRating creditRating = response.Code200;
            
            // The rating
            return creditRating.creditRatingString;
            
        // Handle callout error and translate to application domain exception
        } catch (ExternalService.CreditScore.getAccountLastCreditRating_ResponseException
                e) {
            // Invalid input is flagged with status code 405
            if (e.ResponseCode == 405) {
                throw new CreditScoreException('Invalid input for account: ' + 
                    accountId.accountIdString);
            }
            
            // Handle generic callout error - for example internal server error code 500
            throw new CreditScoreException('Unknown error: ' + e.ResponseCode + ': ' 
                + e.DefaultResponse);
        }
    }
}

External Service Data Types

OpenAPI schema data types are mapped to their corresponding Apex types as follows:

OpenAPI 2/3 Data Types (type, format)	Apex Type
integer	Integer
integer, int32	Integer
integer, int64	Long
number, float	Double
number, double	Double
string	String
string, byte	Blob
string, binary	Blob
string, date	Date
string, date-time	Datetime
boolean	Boolean
array	List<>
object	Apex Property Class, Map<>

Array

The OpenAPI type array is mapped as Apex List<ElementType>. The items type is mapped to ElementType.

Object

The OpenAPI type object is mapped as a named Apex class where the Apex class properties match the OpenAPI properties by property name and type. additionalProperties are mapped as Apex Map<String, ValueType>. The additionalProperties name is the map key, the additionalProperties type is the map’s ValueType.

Object Naming

OpenAPI schema object types defined as a named reference with definitions in OpenAPI 2 or schema components in OpenAPI 3 map to the Apex Property Class type: ExternalService.<Service Name>_<Reference Name>. For example, the credit score’s creditRating object schema is ExternalService.CreditScore_creditRating.

Schema object types anonymously declared inline instead of a named schema reference must be identifiable as an Apex property class by name with this naming scheme:

• Operation request body object schema:
  • ExternalService.<Service Name>_<Operation Name>_IN
• Operation response object schema with successful HTTP status code (< 300):
  • ExternalService.<Service Name>_<Operation Name>_OUT_<Response Code>
• Operation response object schema with error HTTP status code (>= 300):
  • ExternalService.<Service Name>_<Operation Name>_EXC_<Response Code>
• Object schema as property type of another schema object:
  • ExternalService.<Service Name>_<Property's Object Name>_<Property Name>
• Polymorphic object schema in allOf schema composition with discriminator:
  • ExternalService.<Service Name>_<Composition Schema Reference Name>_KT_PT

Array item type with anonymous object schema - Apex Properties Class for list ElementType:

• Element type for named schema referenced array:
  • ExternalService.<Service Name>_VT_<Array Reference Name>
• Element type for anonymous schema array follows the object schema naming scheme

Object’s additionalProperties type with anonymous object schema - Apex Properties Class for map ValueType:

• Map value type for additionalProperties in named reference object schema:
  • ExternalService.<Service Name>_KT_VN_<additonalProperties' Object Reference Name>
• Map value type for addtionalProperties in anonymous object schema:
  • <additionalProperties' Anonymous Object Name>_KT_V

For more object schema type examples, see: Schema Examples.

Variable Naming

When Salesforce maps variable names from your schema into Apex variable names, certain characters are translated.

Schema Variable	Translates Into Apex As	Example
_ (underscore)	x5f	account_type (schema) accountx5ftype (Apex)
- (hyphen)	x2d	account-status (schema) accountx2dstatus (Apex)
(reserved keyword)	prepended with z0	User (schema) z0User (Apex)