---
schema_version: "1"
id: bc85165494d6e70e752e332dc5613a2775c6ebcc0c159614160e97fa8dcc0d9e
title: External Service Registrations in Apex
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/platform/264-0-0/external_services_apex_registrations.md
canonical_url: https://help.salesforce.com/s/articleView?id=platform.external_services_apex_registrations.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: 673107feb7702606da884f8e6adaf89458408a9359facb6a111043f97836b372
description: See how registered external service schema types map to Apex types under the namespace ExternalService.
products:
  - Salesforce Platform
  - Security
release: "264"
---
# External Service Registrations in Apex

See how registered external service schema types map to Apex types under the namespace `ExternalService`.

### Required Editions

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small edition"><colgroup><col></colgroup><tbody><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: Lightning Experience</td></tr><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: <strong>Enterprise</strong>, <strong>Performance</strong>, <strong>Unlimited</strong>, and <strong>Developer</strong> Editions</td></tr></tbody></table>

The example Apex types in this section refer to the [Example 1: Basic OpenAPI Spec with Request and Response (OAS 2.0)](https://help.salesforce.com/s/articleView?id=platform.external_services_schema_examples.htm&release=264.0.0&type=5) with a registered name "CreditScore".

## 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](https://help.salesforce.com/s/articleView?id=platform.external_services_examples.htm&release=264.0.0&type=5 "Explore various scenarios with OpenAPI 2.0 and OpenAPI 3.0 compliant JSON or YAML schemas supported by External Services. The examples cover schema elements like HTTP header as input parameters, and include example usage in Apex. Understanding the examples helps with proper syntax and code placement.").

## Variable Naming

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

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small ">
        <colgroup>
          <col style="width:33.33333333333333%">
          <col style="width:33.33333333333333%">
          <col style="width:33.33333333333333%">
        </colgroup>
        <thead class="slds-text-title_caps ">
          <tr class="">
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d165718e537">Schema Variable</th>
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d165718e540">Translates Into Apex As</th>
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d165718e543">Example</th>
          </tr>
        </thead>
        <tbody>
          <tr class="">
            <td data-label="Schema Variable" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e537 "><code>_</code> (underscore)</td>

            <td data-label="Translates Into Apex As" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e540 ">
              <code>x5f</code>
            </td>

            <td data-label="Example" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e543 ">
              <p><code>account_type</code> (schema)</p>
              <p style="margin-bottom:0;"><code>accountx5ftype</code> (Apex)</p>
            </td>

          </tr>
          <tr class="">
            <td data-label="Schema Variable" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e537 "><code>-</code> (hyphen)</td>

            <td data-label="Translates Into Apex As" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e540 ">
              <code>x2d</code>
            </td>

            <td data-label="Example" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e543 ">
              <p><code>account-status</code> (schema)</p>
              <p style="margin-bottom:0;"><code>accountx2dstatus</code> (Apex)</p>
            </td>

          </tr>
          <tr class="">
            <td data-label="Schema Variable" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e537 ">(reserved keyword)</td>

            <td data-label="Translates Into Apex As" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e540 ">prepended with <code>z0</code></td>

            <td data-label="Example" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e543 ">
              <p><code>User</code> (schema)</p>
              <p style="margin-bottom:0;"><code>z0User</code> (Apex)</p>
            </td>

          </tr>
          <tr class="">
            <td data-label="Schema Variable" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e537 ">&nbsp;</td>

            <td data-label="Translates Into Apex As" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e540 ">&nbsp;</td>

            <td data-label="Example" class="slds-cell-wrap" style="vertical-align:top;" headers="d165718e543 ">&nbsp;</td>

          </tr>
        </tbody>
      </table>