Prerequisites
Generate Files
Verify Files
Limits
Create Actions from Named Queries
Create Custom Actions Using Apex InvocableMethod
Provide Global Copy to Action Responses
Cite Agent Responses with Apex
Use the sample files and table to confirm that the generated OpenAPI document is semantically identical to the REST class it was generated from.
/a/b/c/{id}. HttpGet and HttpDelete typically use an Id that is taken from the URI./a/b/c/{id}, confirm that the parameter is listed in the parameters section with the correct setting for the in property.1openapi: 3.0.0
2servers:
3 - url: /services/apexrest
4info:
5title: CaseManager
6 version: 1.0.0
7 description: This is an auto-generated OpenAPI v3 spec for CaseManager.
8paths:
9 /apex-rest-examples/v1/Cases/{caseId}:
10 description: Default description for the path.
11 get:
12 summary: Retrieve a case by its ID
13 description: Retrieve a case by its ID
14 operationId: getCaseById
15 parameters:
16 - name: caseId
17 in: path
18 required: true
19 description: The ID of the case to retrieve
20 schema:
21 type: string
22 responses:
23 "200":
24 description: Successful response
25 content:
26 application/json:
27 schema:
28 type: object
29 properties:
30 CaseNumber:
31 type: string
32 Subject:
33 type: string
34 Status:
35 type: string
36 Origin:
37 type: string
38 Priority:
39 type: string
40 delete:
41 summary: Delete a case
42 description: Deletes a case based on the provided case ID.
43 operationId: deleteCase
44 parameters:
45 - name: caseId
46 in: path
47 description: The ID of the case to delete
48 required: true
49 schema:
50 type: string
51 responses:
52 "204":
53 description: Case deleted successfully
54 content:
55 application/json:
56 schema:
57 type: object
58 patch:
59 summary: Update Case Fields
60 description: Update fields of a specific case identified by its ID.
61 operationId: updateCaseFields
62 parameters:
63 - name: caseId
64 in: path
65 description: The ID of the case to update
66 required: true
67 schema:
68 type: string
69 requestBody:
70 description: JSON object containing field names and their new values
71 required: true
72 content:
73 application/json:
74 schema:
75 type: object
76 properties:
77 subject:
78 type: string
79 status:
80 type: string
81 origin:
82 type: string
83 priority:
84 type: string
85 responses:
86 "200":
87 description: Successful update of the case
88 content:
89 application/json:
90 schema:
91 type: string
92 /apex-rest-examples/v1/Cases:
93 description: Default description for the path.
94 post:
95 summary: Create a new case
96 description: Creates a new case with the provided details.
97 operationId: createCase
98 requestBody:
99 description: Default description for the requestBody.
100 required: true
101 content:
102 application/json:
103 schema:
104 type: object
105 properties:
106 subject:
107 type: string
108 status:
109 type: string
110 origin:
111 type: string
112 priority:
113 type: string
114 required:
115 - subject
116 - status
117 - origin
118 - priority
119 description: Case creation details
120 responses:
121 "200":
122 description: Successfully created case
123 content:
124 application/json:
125 schema:
126 type: string
127 put:
128 summary: Upsert a case
129 description: Upsert a case based on the provided details.
130 operationId: upsertCase
131 requestBody:
132 description: Default description for the requestBody.
133 required: true
134 content:
135 application/json:
136 schema:
137 type: object
138 properties:
139 id:
140 type: string
141 subject:
142 type: string
143 status:
144 type: string
145 origin:
146 type: string
147 priority:
148 type: string
149 description: Case details for upserting.
150 responses:
151 "200":
152 description: Successful operation
153 content:
154 application/json:
155 schema:
156 type: string1<?xml version="1.0" encoding="UTF-8"?>
2<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
3 <description>This is the ideal OpenAPI v3 specification for CaseManager.cls.</description>
4 <label>CaseManager</label>
5 <schemaType>OpenApi3</schemaType>
6 <schemaUploadFileExtension>yaml</schemaUploadFileExtension>
7 <schemaUploadFileName>casemanager_openapi</schemaUploadFileName>
8 <status>Complete</status>
9 <systemVersion>3</systemVersion>
10 <operations>
11 <name>getCaseById</name>
12 <active>true</active>
13 </operations>
14 <operations>
15 <name>createCase</name>
16 <active>true</active>
17 </operations>
18 <operations>
19 <name>deleteCase</name>
20 <active>true</active>
21 </operations>
22 <operations>
23 <name>upsertCase</name>
24 <active>true</active>
25 </operations>
26 <operations>
27 <name>updateCaseFields</name>
28 <active>true</active>
29 </operations>
30 <registrationProvider>CaseManager</registrationProvider>
31 <registrationProviderType>Custom</registrationProviderType>
32 <namedCredentialReference>null</namedCredentialReference>
33</ExternalServiceRegistration>This table lists objects and fields in the OpenAPI specification that require specific values or actions to make the specification valid for use with Apex classes that you expose as agent actions. Make sure the OpenAPI specification you generate for these Apex classes is in agreement with the descriptions in this table.
| Field | Description |
|---|---|
| OpenAPI Object | |
openapi | Set the OpenAPI Specification version 3.0.0. |
servers | Set the API server definition for the API to a single ‘/services/apexrest’ URL. |
paths | Set the relative paths to the individual endpoints and their operations to exactly match the path defined in the @RestResource annotation’s urlMapping parameter. |
security | Apex REST supports these authentication mechanisms: - Type: OAuth2 - Type: HTTP, Scheme:Bearer |
| Path Item Object | |
description | Provide a detailed description of the path. Supports Markdown syntax. |
servers | Don’t include this field. |
options | Don’t include this field. |
head | Don’t include this field. |
trace | Don’t include this field. |
| Operations Object | |
description | Provide a detailed description of the operation. Supports Markdown syntax. |
operationId | Provide a unique identifier for the operation. Useful for referencing the operation programmatically. |
parameters | Provide a list of unique parameter objects applicable for this operation, as needed. These parameters override matching parameters in the Path Item Object. |
requestBody | Provide a request body describing the input data for this, if needed. |
responses | Provide a responses object specifying the possible responses for the operation, if needed. |
callbacks | Don’t include this field. |
deprecated | Don’t include this field. |
security | Don’t include this field. |
servers | Don’t include this field. |
| Request Body Object | |
description | Provide a brief description of the request body. Can be used for documentation purposes. |
content | Use only application/json for media type. This field is a map of media types and their corresponding schema for the request body. |
| Parameters Object | |
in | Provide query, header, and path parameter locations. Don’t provide cookie. |
description | Provide a brief description of the parameter’s purpose. |
deprecated | Don’t include this field. |
explode | Don’t include this field. |
allowReserved | Don’t include this field. |
example | This field isn’t required, but we recommend that you include it. |
examples | This field isn’t required, but we recommend that you include it. |
content | Use only application/json for media type. This field is a map of media types and their corresponding schema for the parameter. |
| Response Object | |
description | Provide a short description of the response. CommonMark syntax can be used for rich text representation. |
headers | Don’t include this field. Headers aren’t allowed in responses. |
content | Use only application/json if the response has type: object, or text/plain if the response has type: string. This field is a map defining the response body. |
| Media Type Object | |
Encoding | Don’t include this field. |
| Header Object | Don’t use these headers: cookie, set-cookie, set-cookie2, content-length, Authorization. Don’t use allowed headers in response objects. |
description | Provide a brief description of the header’s purpose. |
deprecated | Don’t include this field. |
explode | Don’t include this field. |
allowReserved | Don’t include this field. |
example | This field isn’t required, but we recommend that you include it. |
examples | This field isn’t required, but we recommend that you include it. |
content | Use only application/json for media type. This field is a map of media types and their corresponding schema for the header. |
| Callback Object | Don’t use this object. |
| Schema Object | Include a properties object with the input properties that should be present. Don’t use not blocks. |
These boolean fields extend the OpenAPI specification. Use these fields to define agent actions that are automatically created and made available in agents. For MuleSoft for Agentforce: Topic Center extensions, see Configure Topics.
| Extension | Description |
|---|---|
x-sfdc/agent/action/publishAsAgentAction | Required. Set this attribute to true to enable the operation as an action. |
x-sfdc/privacy/isPii | Optional. If publishAsAgentAction is enabled, set this attribute to true to enable PII service for queries sent under that operation |
x-sfdc/agent/action/isUserInput | Required if publishAsAgentAction is enabled. Set this attribute to true to surface the field to the user for further input. |
x-sfdc/agent/action/isDisplayable | Required if publishAsAgentAction is enabled. Set this attribute to true for the field to be displayable to the user. |
The metadata must be defined inside a schema. For example:
1...
2components:
3 schemas:
4 Pet:
5 x-sfdc:
6 agent:
7 action:
8 isDisplayable: true
9...Don’t add agent metadata in a schema that’s defined using $ref.
ExternalServiceRegistration metadata deploys the OpenAPI document for your Apex REST class. The ExternalServiceRegistration fields are characteristic of an Apex REST service in the API catalog. The table below shows how these fields must be set:
| Field Name | Field Type | Description |
|---|---|---|
namedCredential | string | The field value is always null. The Apex REST service is deployed to your org. |
registrationProvider | string | The name of the Apex REST class implementing the REST service. |
registrationProviderType | enum string | Indicates the type of the API specification registration. New enumeration value: ApexRest - The API spec is implemented by an Apex REST class in your org. |
schema | string | The content of the OpenAPI 3.0 schema in YAML format. This field is empty if your SFDX project source behavior has been configured to decompose the ExternalServiceRegistration metadata. |
schemaType | string | OpenApi3 |
ESR of provider type ApexRest aren’t visible in the External Service Setup. From Setup, in the Quick Find box, enter API Catalog and select it. See View Apex APIs in API Catalog.
Note
Deploying the ExternalServiceRegistration with registration provider type ApexRest doesn’t co-deploy the Apex REST class implementing the service automatically. You must deploy the Apex REST class as part of your project or on its own.
Note
In the MuleSoft for Agentforce Extension Pack, the MuleSoft for Agentforce API Design Extension provides the ability to check that your document is semantically and syntactically correct in Code Builder. The MuleSoft for Agentforce Extension Pack contains these extensions:
The Salesforce API Topic and Action Enablement and Salesforce Apex REST Best Practices governance rulesets are included in the MuleSoft for Agentforce Extension Pack. Use the governance rules in the extension pack to ensure that your document is ready for agent actions and has the required metadata to generate agent actions. Use these commands.
For details, see Validating API Specifications Against Governance Rulesets and Enabling an API Project for Topics and Agent Actions.
In the API Console, you can check endpoints and test your document by providing a deployed instance of your Apex REST implementation or by mocking up request data. For details, see Review Your Spec in the API Console and Test Your Spec Using the API Mocking Service.