This section features External Services OpenAPI 3.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 3.0)
Here’s an example of an API spec that contains a supported JSON schema for OpenAPI 3.0. The
parameters contain the definition for the accountId input. The responses
contain the definition for the output, which is creditRating. Parameters,
requests, and responses translate to inputs and outputs, respectively, for your flow
actions.
{
"openapi": "3.0.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"
}
},
"servers": [
{
"url": "https://<YourHostName>"
}
],
"paths": {
"/account/lastCreditRating": {
"get": {
"summary": "Evaluates credit rating and decides what payment terms to offer.",
"description": "",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/accountId"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/accountId"
}
}
},
"description": "Specifies input parameters to calculate payment term",
"required": true
},
"responses": {
"200": {
"description": "success",
"content": {
"application/xml": {
"schema": {
"$ref": "#/components/schemas/creditRating"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/creditRating"
}
}
}
},
"405": {
"description": "Invalid input"
}
}
}
}
},
"components": {
"schemas": {
"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 3.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 paste in the schema at registration time, instead of by 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 schema.
- The banking system's external service shows two ways to define parameters with object
types: a named object type under a "components/schema" 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 schema with the named object type defined under the "components/schema" block. The phone object type's name is ExternalService__Bank_Phone in Apex or Flow Builder.
{
"openapi": "3.0.0",
"info": {
"title": "bankService",
"description": "API description in Markdown.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.example.com/v1"
}
],
"components": {
"schemas": {
"User": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones": {
"type": "array",
"items": {
"$ref": "#/components/schemas/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,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
},
"/users": {
"post": {
"summary": "Creates a new user.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
Example 3: Nested Anonymous Object Schema (OAS 3.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.
Note For anonymous object types, Salesforce automatically derives object type names. The
derived names are based on the external service, parent operation, operation parameter,
parent object, and object property names. Each derived name must be fewer than 255
characters. For more information, see Schema Definition Support.
{
"openapi": "3.0.0",
"info": {
"title": "bankService",
"description": "API description in Markdown.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.example.com/v1"
}
],
"paths": {
"/users/{userId}": {
"get": {
"summary": "Returns a user by ID.",
"parameters": [
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"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.",
"requestBody": {
"content": {
"application/json": {
"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 3.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).
Tip If the derived object name is longer than 255 characters, try one of these
methods to resolve the issue.
- 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 "components/schemas".
{
"openapi": "3.0.0",
...
"paths": {
"/balance/account/{accountId}/type/checking": {
"get": {
"parameters": [
{
"in": "path",
"name": "accountId",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"*/*": {
"schema": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"owner": {
"$ref": "#/components/schemas/VeryImportantCustomer"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"VeryImportantCustomer": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"phone": {
"type": "object",
"properties": {
"number": {
"type": "string"
}
}
}
}
}
}
}
}
Example 5: Shortening Apex Object Class Names (OAS 3.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
{
"openapi": "3.0.0",
...
"paths": {
"/balance/account/{accountId}/type/checking": {
"get": {
"operationId": "getBalance",
"parameters": [
{
"in": "path",
"name": "accountId",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"owner": {
"$ref": "#/components/schemas/VIP"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"VIP": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"phone": {
"type": "object",
"properties": {
"number": {
"type": "string"
}
}
}
}
}
}
}
}
Example 6: Inline Arrays (OAS 3.0)
Here's an example with an inline array definition.
{
"openapi": "3.0.0",
...
"paths": {
"/employees/{employeeId}": {
"get": {
"operationId": "getEmployee",
"parameters": [
{
"in": "path",
"name": "employeeId",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"employee": {
"$ref": "#/components/schemas/Employee"
},
"manager": {
"$ref": "#/components/schemas/Employee"
},
"team": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee"
}
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"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 3.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.
{
"openapi": "3.0.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"
}
},
"servers": [
{
"url": "https://<YourHostName>"
}
],
"paths": {
"/account/lastCreditRating": {
"get": {
"summary": "Evaluates credit rating and decides what payment terms to offer.",
"description": "",
"parameters": [
{
"name": "apiKey",
"description": "Your API Key for calling the credit rating service",
"in": "header",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/accountId"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/accountId"
}
}
},
"description": "Specifies input parameters to calculate payment term",
"required": true
},
"responses": {
"200": {
"description": "success",
"content": {
"application/xml": {
"schema": {
"$ref": "#/components/schemas/creditRating"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/creditRating"
}
}
}
},
"405": {
"description": "Invalid input"
}
}
}
}
},
"components": {
"schemas": {
"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 3.0)
Request and response form data is declared with media type
application/x-www-form-urlencoded.
{
"openapi": "3.0.0",
"info": {
"description": "Apply here for your next mortgage",
"version": "1.0.0",
"title": "My Mortgage Buddy",
"contact": {
"email": "apiteam@swagger.io"
}
},
"servers": [
{
"url": "https://MyMortgageBuddy.org/mortgages"
}
],
"paths": {
"/apply": {
"post": {
"operationId": "applyMortgage",
"requestBody": {
"content": {
"application/x-www-form-urlencoded; charset=utf-8": {
"schema": {
"type": "object",
"properties": {
"terms": {
"description": "Desired mortgage terms",
"type": "array",
"items": {
"type": "integer"
}
},
"fullName": {
"description": "Full Name",
"type": "string"
},
"loanAmount": {
"description": "Loan amount",
"type": "number"
}
},
"required": [
"terms",
"fullName",
"loanAmount"
]
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/x-www-form-urlencoded; charset=utf-8": {
"schema": {
"type": "object",
"properties": {
"formApplicationId": {
"type": "string"
},
"loanOfficerFullName": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
Example 9: allOf and additionalProperties Schema Directives (OAS 3.0)
This JSON schema definition highlights the constructs allOf for schema
object composition and additionalProperties for dictionary values. The
sample schema is registered as external service MyBank with named
credential MyBank.
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. PhonesandEmailscompose their own properties together with the commonallOfproperties from the schema objectContact.
{
"openapi": "3.0.0",
"info": {
"title": "myBank",
"description": "Sample Banking Service with allOf and additionalProperties",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.mybank.com/v1"
}
],
"paths": {
"/customers/{customerId}": {
"get": {
"summary": "Get the customer by ID.",
"parameters": [
{
"in": "path",
"name": "customerId",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Phone"
}
},
"emails": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Email"
}
}
},
"additionalProperties": {
"$ref": "#/components/schemas/CreditRating"
},
"required": [
"id",
"name"
]
},
"Contact": {
"type": "object",
"properties": {
"primary": {
"type": "boolean"
},
"timeOfDay": {
"type": "string"
}
},
"required": [
"primary"
]
},
"Phone": {
"allOf": [
{
"$ref": "#/components/schemas/Contact"
},
{
"type": "object",
"properties": {
"typeOfPhone": {
"type": "string"
},
"phoneNumber": {
"type": "string"
}
}
}
]
},
"Email": {
"allOf": [
{
"$ref": "#/components/schemas/Contact"
},
{
"type": "object",
"properties": {
"email": {
"type": "string"
}
}
}
]
},
"CreditRating": {
"type": "object",
"properties": {
"rating": {
"type": "string"
},
"score": {
"type": "number",
"format": "double"
}
}
}
}
}
}
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 3.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:
{
"openapi": "3.0.0",
"info": {
"title": "myBank",
"description": "Sample Banking Service with allOf and discriminator",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.mybank.com/v1"
}
],
"paths": {
"/customers/{customerId}": {
"get": {
"summary": "Get the customer by ID.",
"parameters": [
{
"in": "path",
"name": "customerId",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"contacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Contact"
}
}
},
"required": [
"id",
"name"
]
},
"Contact": {
"type": "object",
"discriminator": {
"propertyName": "contactType"
},
"properties": {
"contactType": {
"type": "string"
},
"primary": {
"type": "boolean"
},
"timeOfDay": {
"type": "string"
}
},
"required": [
"contactType",
"primary"
]
},
"Phone": {
"allOf": [
{
"$ref": "#/components/schemas/Contact"
},
{
"type": "object",
"properties": {
"typeOfPhone": {
"type": "string"
},
"phoneNumber": {
"type": "string"
}
}
}
]
},
"Email": {
"allOf": [
{
"$ref": "#/components/schemas/Contact"
},
{
"type": "object",
"properties": {
"email": {
"type": "string"
}
}
}
]
}
}
}
}
To use composition and polymorphic OpenAPI schema constructs, see For Examples 10: Polymorphism with allOf and Discriminator.
Example 11: anyOf, oneOf, and Discriminator Directives (OAS 3.0)
anyOf and oneOf directives model types with parts of a
common schema type. anyOf and oneOf can be combined with
the schema construct discriminator for polymorphic types.
- Social security number
- The driver's license number
- The customer's first and last name with optional middle name
In the example, a customer can be identified by one or more of the following allowed identifiers.
The schema mandates both the customer's first and last name, or to choose any other allowed identification.
This example also highlights a variation of the Contact type polymorphism with
oneOf and discriminator from Example 10 with
allOf.
{
"openapi": "3.0.0",
"info": {
"title": "myBank",
"description": "Sample Banking Service with oneOf, anyOf and discriminator",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.mybank.com/v1"
}
],
"paths": {
"/customers/{customerId}": {
"get": {
"summary": "Get the customer by ID.",
"parameters": [
{
"in": "path",
"name": "customerId",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Customer": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"$ref": "#/components/schemas/SSN"
},
{
"$ref": "#/components/schemas/DriversLicense"
},
{
"$ref": "#/components/schemas/FullName"
}
]
},
"contacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Contact"
}
}
},
"required": [
"id"
]
},
"SSN": {
"type": "object",
"properties": {
"ssn": {
"type": "string"
}
},
"required": [
"ssn"
]
},
"DriversLicense": {
"type": "object",
"properties": {
"dl": {
"type": "string"
}
},
"required": [
"dl"
]
},
"FullName": {
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"middleName": {
"type": "string"
},
"lastName": {
"type": "string"
}
},
"required": [
"firstName",
"lastName"
]
},
"Contact": {
"oneOf": [
{
"$ref": "#/components/schemas/Phone"
},
{
"$ref": "#/components/schemas/Email"
}
],
"discriminator": {
"propertyName": "contactType"
}
},
"Phone": {
"type": "object",
"properties": {
"contactType": {
"type": "string"
},
"typeOfPhone": {
"type": "string"
},
"phoneNumber": {
"type": "string"
}
}
},
"Email": {
"type": "object",
"properties": {
"contactType": {
"type": "string"
},
"email": {
"type": "string"
}
}
}
}
}
}
To use composition and polymorphic OpenAPI schema constructs, see For Example 11 (Open API 3.0): AnyOf, OneOf, and Discriminator.
Example 12: Callbacks (OAS3.0)
External Services specify callback options through the OpenAPI 3.0 schema’s
callbacks object.
This is an example of a callback for a mortgage application process for the fictitious company Acme Mortgages.
openapi: 3.0.0
info:
version: '1.0'
title: Acme Mortgages
description: Acme Mortgages
paths:
# Example of synchronous operation GetApplication
/applications/{applicationNumber}:
get:
operationId: GetApplication
description: Get the mortgage application status and details
parameters:
- name: applicationNumber
in: path
required: true
description: Mortgage Application Number
schema:
type: string
- name: referenceId
in: query
description: Reference ID if applicable. Either as query or header
schema:
type: string
- name: referenceId
in: header
description: Reference ID if applicable. Either as query or header
schema:
type: string
responses:
200:
description: Mortgage application status
content:
application/json:
schema:
$ref: '#/components/schemas/MortgageApplication'
/applications:
# Example of asynchronous operation with callback SubmitApplication
post:
operationId: SubmitApplication
description: Submit a new mortgage application
requestBody:
content:
application/json:
schema:
type: object
properties:
applicant:
$ref: '#/components/schemas/Contact'
object:
$ref: '#/components/schemas/Contact'
statusUpdateRequest:
$ref: '#/components/schemas/ApplicationStatusUpdateRequest'
callbackUrl:
type: object
properties:
outcome:
type: object
properties:
approved:
type: string
rejected:
type: string
documentation:
type: string
outcomeError:
type: string
responses:
200:
description: Mortgage loan application submission response
content:
application/json:
schema:
type: object
properties:
applicationNumber:
type: string
400:
description: Mortgage application error
content:
application/json:
schema:
$ref: '#/components/schemas/MortgageApplicationError'
callbacks:
applicationOutcome:
'{$request.body#/callbackUrl/outcome/approved}':
post:
operationId: ApplicationApproved
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MortgageApplication'
responses:
200:
description: Approved mortgage application callback accepted
'{$request.body#/callbackUrl/outcome/rejected}':
post:
operationId: ApplicationRejected
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MortgageApplication'
responses:
200:
description: Rejected mortgage application callback accepted
applicationDocumentation:
'{$request.body#/callbackUrl/documentation}':
post:
parameters:
- in: query
name: applicationNumber
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MortgageApplicationDocumentation'
responses:
200:
description: Mortgage application documentation callback accepted
applicationStatus_Update:
$ref: '#/components/callbacks/ApplicationStatus_Update'
applicationOutcomeError:
$ref: '#/components/callbacks/applicationOutcomeError'
servers:
- url: '/'
components:
schemas:
MortgageApplication:
required:
- applicationNumber
- status
properties:
applicationNumber:
type: string
status:
description: One of pending, approved, rejected
type: string
requestedAmount:
type: number
approvedAmount:
type: number
appliedOn:
type: string
format: date-time
updatedOn:
type: string
format: date-time
applicant:
$ref: '#/components/schemas/Contact'
object:
$ref: '#/components/schemas/Contact'
ApplicationStatusUpdateRequest:
description: Mortgage application status update request
type: object
properties:
sendStatusUpdates:
type: boolean
statusUpdateCallbackUrl:
type: string
MortgageApplicationDocumentation:
description: Required mortgage documentation
type: array
items:
type: object
properties:
documentType:
type: string
uploadUrl:
type: string
instructions:
type: string
Contact:
type: object
properties:
name:
type: string
address:
type: string
MortgageApplicationError:
properties:
errorMessage:
type: string
applicationNumber:
type: string
callbacks:
ApplicationStatus_Update:
'{$request.body#/statusUpdateRequest/statusUpdateCallbackUrl}':
post:
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
applicationNumber:
type: string
status:
type: string
updateMessage:
type: string
responses:
200:
description: Mortgage application status update callback accepted
applicationOutcomeError:
'{$request.body#/callbackUrl/outcomeError}':
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MortgageApplicationError'
responses:
200:
description: Mortgage application callback error acceptedExample 13: File Upload and Download (OAS 3.0)
This spec contains these examples:
- A PUT operation for file upload—the PUT operation takes a
keyparameter with the location/file name of the file to upload and specifies thecontent-typeheader. TherequestBodyis defined as a binary string, and contains the contents of the file being uploaded. - A GET operation for file download—the GET operation takes a
keyparameter with the file name of the file to download. The 200 response returns acontentobject defined as a binary string, and contains the contents of the file being downloaded.
This spec references uploading a file to Amazon S3, but the spec can be used to upload files to any system for which you have a named credential configured.
openapi: 3.0.0
info:
title: S3 PutObject and GetObject API
version: 1.1.0
description: Example API for uploading and downloading files to Amazon S3 (without auth headers)
paths:
/{key}:
put:
summary: Upload an object to S3 at the specified key
description: Upload a file to the given bucket and key using HTTP PUT.
operationId: putObject
parameters:
- name: key
in: path
required: true
description: The key (path) of the S3 object
schema:
type: string
- name: Content-Type
in: header
description: MIME type of the uploaded file
schema:
type: string
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
description: Binary content of the file to upload
responses:
'200':
description: Upload successful
headers:
ETag:
description: The ETag of the uploaded object
schema:
type: string
'400':
description: Bad request
'404':
description: Bucket or key not found
'500':
description: Internal server error
get:
summary: Download an object from S3 at the specified key
description: Download the file content from the given bucket and key using HTTP GET.
operationId: getObject
parameters:
- name: key
in: path
required: true
description: The key (path) of the S3 object
schema:
type: string
responses:
'200':
description: File content returned
content:
application/octet-stream:
schema:
type: string
format: binary
'403':
description: Access denied
'404':
description: Object not found
'500':
description: Internal server error
To use this functionality, see For Example 13 (Open API 3.0): Binary File Upload and For Example 13 (Open API 3.0): Binary File Download.
Example 14: Enum Parameters in Queries and Responses (OAS 3.0)
This spec contains a GET operation that takes two enum values as parameters:
- An
ItemStatusparameter that contains a value from the ItemStatus enum. - An
ItemPriorityparameter that contains a value from the ItemPriority enum.
The 200 response returns an object that contains the item id, status, priority, and description.
{
"openapi": "3.0.3",
"info": {
"title": "Enum Examples API",
"version": "1.0.0",
"description": "Example API demonstrating enum parameters in queries and responses."
},
"servers": [
{
"url": "https://abc-mock-api-123456789123.herokuapp.com/"
}
],
"paths": {
"/items": {
"get": {
"operationId": "getItemList",
"summary": "Retrieve a list of items filtered by enum parameters",
"parameters": [
{
"name": "status",
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/ItemStatus"
},
"description": "Filter items by their status"
},
{
"name": "priority",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/ItemPriority"
},
"description": "Optional filter for item priority"
}
],
"responses": {
"200": {
"description": "Successful response with list of items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemResponse"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ItemStatus": {
"type": "string",
"enum": [
"active",
"inactive",
"pending",
"archived"
]
},
"ItemPriority": {
"type": "integer",
"enum": [
1,
2,
3,
4,
5
]
},
"ItemResponse": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"status": {
"$ref": "#/components/schemas/ItemStatus"
},
"priority": {
"$ref": "#/components/schemas/ItemPriority"
},
"message": {
"type": "string",
"description": "Additional information about the item"
}
},
"required": [
"id",
"status"
]
}
}
}
}
Example 15: Any Type Support by Using schema: {} (OAS 3.0)
This spec contains a POST method that takes any JSON string. Any type support is only available for orgs that have Data 360 provisioned.
You can also use a mixed structure in your spec that combines typed parameters with an any type body. For example, define typed query parameters, path parameters, or headers for event metadata while keeping the request body as any type.
openapi: 3.0.1
info:
title: Flow Any Type Test Service
description: |
Minimal OAS3 spec for any type support
version: 1.0.0
servers:
- url: https://sample.com
paths:
/test:
post:
operationId: sendTestPayload
summary: Accepts any JSON payload (anytype body)
requestBody:
required: false
content:
application/json:
schema: {}
responses:
'200':
description: Payload accepted
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: ok