External Services OpenAPI 2.0 Schema
This section features External Services OpenAPI 2.0 schema examples.
Required Editions
| Available in: Lightning Experience |
| Available in: Enterprise, Performance, Unlimited, and Developer Editions |
Example 1: Basic OpenAPI Spec with Request and Response (OAS 2.0)
Here’s an example of an API spec that contains a supported JSON schema for OpenAPI
2.0. The parameters (in bold) contain the definition for the accountId input. The responses (also in bold)
contain the definition for the output, which is creditRating. Parameters and responses translate to inputs and
outputs, respectively, for your flow actions.
{
"swagger":"2.0",
"info":{
"description":"A service for checking credit for an account.",
"version":"1.0.0",
"title":"Credit Decision",
"termsOfService":"http://swagger.io/terms/",
"contact":{
"email":"apiteam@swagger.io"
},
"license":{
"name":"Apache 2.0",
"url":"http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"host":"<YourHostName>",
"paths":{
"/account/lastCreditRating":{
"get":{
"summary":"Evaluates credit rating and decides what payment terms to offer.",
"description":"",
"consumes":[
"application/json",
"application/xml"
],
"produces":[
"application/xml",
"application/json"
],
"parameters":[{
"in":"body",
"name":"body",
"description":"Specifies input parameters to calculate payment term",
"required":true,
"schema":{
"$ref":"#/definitions/accountId"
}
}],
"responses":{
"200":{
"description":"success",
"schema":{
"$ref":"#/definitions/creditRating"
}
},
"405":{
"description":"Invalid input"
}
}
}
}
},
"definitions":{
"accountId":{
"type":"object",
"properties":{
"accountIdString":{
"type":"string"
}
},
"xml":{
"name":"accountId"
}
},
"creditRating":{
"type":"object",
"properties":{
"creditRatingString":{
"type":"string"
}
},
"xml":{
"name":"creditRating"
}
}
}
}Example 2: Named Object Schema Reference (OAS 2.0)
Basic Setup
- For the named credential that your org uses to access the banking system, assign the Bank label and a placeholder URL, such as https://api.example.com. Use example.com because you’ll paste in the schema at registration time, instead of using a URL to point to an API spec.
- Register the employee banking system’s external service. Use the Bank name and the Bank named credential, and then copy and paste in the following schema.
- The banking system's external service shows two ways to define parameters with
object types: a named object type under a “definitions”
block or an anonymously declared object type inline.
Note The defined or derived parameter object type name, or a property with an object type, must be fewer than 255 characters to be used in Apex or Flow Builder.
Here’s a JSON-formatted schema with the named object type defined under the “definitions” block. The phone object type's name is ExternalService__Bank_Phone in Apex or Flow Builder.
{
"swagger": "2.0",
"info": {
"title": "bankService",
"description": "API description in Markdown.",
"version": "1.0.0"
},
"host": "api.example.com",
"basePath": "/v1",
"schemes": [
"https"
],
"definitions": {
"User": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones":{
"type":"array",
"items":{
"type": "object",
"$ref": "#/definitions/Phone"
}
}
}
},
"Phone":{
"properties":{
"typeofphone":{
"type":"string"
},
"phone":{
"type":"string"
}
}
}
},
"paths": {
"/users/{userId}": {
"get": {
"summary": "Returns a user by ID.",
"parameters": [{
"in": "path",
"name": "userId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/User"
}
}
}
}
},
"/users": {
"post": {
"summary": "Creates a new user.",
"parameters": [{
"in": "body",
"name": "user",
"schema": {
"$ref": "#/definitions/User"
}
}],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}Here's the same schema, but formatted with YAML.
swagger: '2.0'
info:
title: bankService
description: API description in Markdown.
version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
- https
definitions:
User:
properties:
id:
type: integer
name:
type: string
phones:
type: array
items:
type: object
$ref: '#/definitions/Phone'
Phone:
properties:
typeofphone:
type: string
phone:
type: string
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/User'
/users:
post:
summary: Creates a new user.
parameters:
- in: body
name: user
schema:
$ref: '#/definitions/User'
responses:
'200':
description: OK
Example 3: Nested Anonymous Object Schema (OAS 2.0)
Here’s an API spec with a JSON schema with anonymous object types defined inline. The derived phone object type's name is ExternalService__Bank_getUsers_OUT_200_phones.
{
"swagger": "2.0",
"info": {
"title": "bankService",
"description": "API description in Markdown.",
"version": "1.0.0"
},
"host": "api.example.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/users/{userId}": {
"get": {
"summary": "Returns a user by ID.",
"parameters": [{
"in": "path",
"name": "userId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones": {
"type":"array",
"items": {
"type": "object",
"properties": {
"typeofphone": {
"type":"string"
},
"phone": {
"type":"string"
}
}
}
}
}
}
}
}
}
},
"/users": {
"post": {
"summary": "Creates a new user.",
"parameters": [{
"in": "body",
"name": "user",
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones": {
"type":"array",
"items": {
"type": "object",
"properties": {
"typeofphone": {
"type":"string"
},
"phone": {
"type":"string"
}
}
}
}
}
}
}],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}Example 4: Apex Object Class Naming (OAS 2.0)
Here's an API spec registered with the external service name BankingAutomaticTellerMachine. However, the derived object names must be no longer than 255 characters:
- ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone
- ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200
To use Apex or Flow Builder, you must shorten the external service schema name and the schema (shown in Example 5).
- Shorten the external service name.
- If the object is declared inline under an operation parameter, shorten the operation name by adding an operationId to the schema.
- If the object is declared inline under a parent object property, shorten the parent object name in the schema.
- Declare the nested object as a top-level object under schema “definitions”.
{
"swagger": "2.0",
...
"paths": {
"/balance/account/{accountId}/type/checking": {
"get": {
"parameters": [{
"in": "path",
"name": "accountId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"schema": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"owner": {
"$ref": "#/definitions/VeryImportantCustomer"
}
}
}
}
}
}
}
},
"definitions": {
"VeryImportantCustomer": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"phone": {
"type": "object",
"properties": {
"number": {
"type": "string"
}
}
}
}
}
}
}Example 5: Shortening Apex Object Class Names (OAS 2.0)
Here's an example of an API spec with a schema that results in shortened names. It's registered with the shortened name BankAtm.
Shorten the external service schema name to BankAtm, the schema object name to VIP and add operationId as getBalance:
- ExternalService__BankAtm_VIP_phone
- ExternalService__BankAtm_getBalance_200
{
"swagger": "2.0",
...
"paths": {
"/balance/account/{accountId}/type/checking": {
"get": {
"operationId": "getBalance",
"parameters": [{
"in": "path",
"name": "accountId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"schema": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"owner": {
"$ref": "#/definitions/VIP"
}
}
}
}
}
}
}
},
"definitions": {
"VIP": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"phone": {
"type": "object",
"properties": {
"number": {
"type": "string"
}
}
}
}
}
}
}Example 6: Inline Arrays (OAS 2.0)
Here's an example with an inline array definition.
{
"swagger": "2.0",
"host": "Employees.org",
"basePath": "/",
...
"paths": {
"/employees/{employeeId}": {
"get": {
"operationId": "getEmployee",
"parameters": [{
"in": "path",
"name": "employeeId",
"required": true,
"type": "string"
}],
"responses": {
"200": {
"schema": {
"type": "object",
"properties": {
"employee": {"$ref": "#/definitions/Employee"},
"manager": {"$ref": "#/definitions/Employee"},
"team": {
"type": "array",
"items": {"$ref": "#/definitions/Employee"}
}
}
}
}
}
}
}
},
"definitions": {
"Employee" : {
"type": "object",
"properties": {
"employeeId": {"type": "string"},
"firstName": {"type": "string"},
"middleName": {"type": "string"},
"lastName": {"type": "string"},
"dateOfHire": {"type": "date"}
}
}
}
}
}
Example 7: HTTP Header Parameters (OAS 2.0)
Here’s how a header parameter is declared in an OpenAPI schema. In Apex or Flow, the
name “apiKey” shows up as a string parameter.
Now when you set any string value in Apex or a flow to apiKey, it functions as an HTTP parameter when making a callout
request.
{
"swagger": "2.0",
"info": {
"description": "A service for checking credit for an account.",
"version": "1.0.0",
"title": "Credit Decision",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"email": "apiteam@swagger.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"host": "<YourHostName>",
"paths": {
"/account/lastCreditRating": {
"get": {
"summary": "Evaluates credit rating and decides what payment terms to offer.",
"description": "",
"consumes": [
"application/json",
"application/xml"
],
"produces": [
"application/xml",
"application/json"
],
"parameters": [{
"name": "body",
"description": "Specifies input parameters to calculate payment term",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/accountId"
}
},{
"name": "apiKey",
"description": "Your API Key for calling the credit rating service",
"in": "header",
"type": "string"
}],
"responses": {
"200": {
"description": "success",
"schema": {
"$ref": "#/definitions/creditRating"
}
},
"405": {
"description": "Invalid input"
}
}
}
}
},
"definitions": {
"accountId": {
"type": "object",
"properties": {
"accountIdString": {
"type": "string"
}
},
"xml": {
"name": "accountId"
}
},
"creditRating": {
"type": "object",
"properties": {
"creditRatingString": {
"type": "string"
}
},
"xml": {
"name": "creditRating"
}
}
}
}Example 8: URL Encoded Form Media Type (OAS 2.0)
Request and response form data is declared alongside the matching consumes and produces directives.
{
"swagger": "2.0",
"info": {
"description": "Apply here for your next mortgage",
"version": "1.0.0",
"title": "My Mortgage Buddy",
"contact": {
"email": "apiteam@swagger.io"
}
},
"host": "MyMortgageBuddy.org",
"basePath": "/mortgages",
"paths": {
"/apply": {
"post": {
"operationId": "applyMortgage",
"consumes": [
"application/x-www-form-urlencoded; charset=utf-8"
],
"produces": [
"application/x-www-form-urlencoded; charset=utf-8"
],
"parameters": [{
"description": "Desired mortgage terms",
"name": "terms",
"in": "formData",
"type": "array",
"items": {
"type": "integer"
},
"collectionFormat": "multi",
"required": true
},{
"description": "Full Name",
"name": "fullName",
"in": "formData",
"type": "string",
"required": true
},{
"description": "Loan amount",
"name": "loanAmount",
"in": "formData",
"type": "number",
"required": true
}],
"responses": {
"200": {
"description": "200",
"schema": {
"type": "object",
"properties": {
"formApplicationId": {
"type": "string"
},
"loanOfficerFullName": {
"type": "string"
}
}
}
}
}
}
}
}
}
Example 9: allOf and additionalProperties Schema Directives (OAS 2.0)
This JSON schema definition highlights the constructs allOf for schema object composition and additionalProperties for dictionary values. The sample schema is
registered as an external service MyBank with
named credential MyBank. The registration is
invoked by a sample flow that accesses the dictionary properties with an Apex
invocable action. A flow Apex unit test ties it all together.
The schema defines a banking service that gets customer details for a customer ID.
- The
Customerschema object has dictionary properties of type schema objectCreditRating. In Apex, the classExternalService.MyBank_Customerhas propertypropertiesof typeMap<String, ExternalService_CreditRating>with the customer’s credit ratings. - Phones and Emails compose their own properties together with the common
allOfproperties from the schema objectContact.
{
"swagger": "2.0",
"info": {
"title": "myBank",
"description": "Sample Banking Service with allOf and additionalProperties schema constructs",
"version": "1.0.0"
},
"host": "api.mybank.com",
"basePath": "/v1",
"schemes": [
"https"
],
"definitions": {
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones": {
"type":"array",
"items": {
"$ref": "#/definitions/Phone"
}
},
"emails": {
"type": "array",
"items": {
"$ref": "#/definitions/Email"
}
}
},
"additionalProperties": {
"$ref": "#/definitions/CreditRating"
},
"required": [
"id",
"name"
]
},
"Contact": {
"type": "object",
"properties": {
"primary": {
"type": "boolean"
},
"timeOfDay": {
"type": "string"
}
},
"required": [
"primary"
]
},
"Phone": {
"allOf": [
{
"$ref": "#/definitions/Contact"
},
{
"type": "object",
"properties": {
"typeOfPhone": {
"type":"string"
},
"phoneNumber":{
"type":"string"
}
}
}
]
},
"Email": {
"allOf": [
{
"$ref": "#/definitions/Contact"
},
{
"type": "object",
"properties": {
"email": {
"type":"string"
}
}
}
]
},
"CreditRating": {
"type": "object",
"properties": {
"rating": {
"type": "string"
},
"score": {
"type": "number",
"format": "double"
}
}
}
},
"paths": {
"/customers/{customerId}": {
"get": {
"summary": "Get the customer by ID.",
"parameters": [{
"in": "path",
"name": "customerId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Customer"
}
}
}
}
}
}
}To use allOf composition and additionalProperties, see For Examples 9: allOf Composition and additionalProperties Use in Flow with Apex Unit Tests.
Example 10: allOf and Discriminator Directives (OAS 2.0)
To specify a general extensible list of contacts for a customer, the discriminator directive can be combined with
allOf to declare whether a contact is an
email or a phone number:
{
"swagger": "2.0",
"info": {
"title": "myBank",
"description": "Sample Banking Service with allOf and discriminator",
"version": "1.0.0"
},
"host": "api.mybank.com",
"basePath": "/v1",
"schemes": [
"https"
],
"definitions": {
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"contacts": {
"type":"array",
"items": {
"$ref": "#/definitions/Contact"
}
}
},
"required": [
"id",
"name"
]
},
"Contact": {
"type": "object",
"discriminator": "contactType",
"properties": {
"contactType": {
"type": "string"
},
"primary": {
"type": "boolean"
},
"timeOfDay": {
"type": "string"
}
},
"required": [
"contactType",
"primary"
]
},
"Phone": {
"allOf": [
{
"$ref": "#/definitions/Contact"
},
{
"type": "object",
"properties": {
"typeOfPhone": {
"type":"string"
},
"phoneNumber":{
"type":"string"
}
}
}
]
},
"Email": {
"allOf": [
{
"$ref": "#/definitions/Contact"
},
{
"type": "object",
"properties": {
"email": {
"type":"string"
}
}
}
]
}
},
"paths": {
"/customers/{customerId}": {
"get": {
"summary": "Get the customer by ID.",
"parameters": [{
"in": "path",
"name": "customerId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Customer"
}
}
}
}
}
}
}
To use composition and polymorphic OpenAPI schema constructs, see For Examples 10: Polymorphism with allOf and Discriminator.
Array Definition (OAS 2.0)
External Services supports inline array definitions and referenceable named arrays. List types in External Services are identified by their object element type.
Supported Inline Array Definition with Reference to Array Items Definition
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"type": "array",
"items": {
"$ref": "#definitions/MyObject"
}
}
...
"definitions": {
"MyObject": {
"type": "object",
"properties": {...}
}
}
}In Apex and Flow Builder, declare a variable for the myObjects parameter by marking the variable as a collection and
picking its Apex element type ExternalService__RegistrationName_MyObject.
Inline Array Definition with Inline Array Items Definition
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {...}
}
}
...
"definitions": {
...
}
}In Apex and Flow Builder, declare a collection variable for the myObjects parameter and Apex element type ExternalService__RegistrationName_OperationName_IN_myObjects.
Referenceable Array Definition with Reference to Array Item Definitions
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"$ref": "#definitions/MyObjectList"
}
...
"definitions": {
"MyObjectList": {
"type": "array",
"items": {
"$ref": "#definitions/MyObject"
}
}
"MyObject": {
"type": "object",
"properties": {...}
}
}
}In Apex and Flow Builder, declare a collection variable for the myObjects parameter and Apex element type ExternalService__RegistrationName_MyObject.
Referenceable Array Definition with Inline Array Items Definition
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"$ref": "#definitions/MyObjectList"
}
...
"definitions": {
"MyObjectList": {
"type": "array",
"items": {
"type": "object",
"properties": {...}
}
}
}
}In Apex and Flow Builder, declare a collection variable for the myObjects parameter and Apex element type ExternalService__RegistrationName_MyObjectList.
