Skip to content

Latest commit

 

History

History
191 lines (126 loc) · 8.82 KB

salesforce-functions-api.md

File metadata and controls

191 lines (126 loc) · 8.82 KB
Raw
description
An open-source API specification for Salesforce Functions

Salesforce Functions API

Goal

Apex Functions support for server SDK developed in ANY programming language hosted in ANY infrastructure, be it local or cloud.

Develop an open standard so anyone can develop a server SDK on any programming language and deploy it to any cloud provider. This can be open source or commercial.

Salesforce to Provide

  • Provide a set of Apex interfaces. Keep them compatible with the current SF Function implementation.
  • Provide the message structures (JSON Schema) that will be used to communicate between SF Function and the server
  • Provide a set of Testing assets to test the implementation to ensure they meet the standards. These will be Apex and also Postman projects.

Server Side SDK provider to provide at a minimum.

  • Support the Functions messaging standard.
  • Request-Reply support (1:1)
  • Call back support (1:1 and 1:M)
  • Ability to perform CRUD on Salesforce object
  • Pass the Apex Functions confirmation Test.

The client-server communication is based on open standards (Cloud Events); thus, any Cloud Events client can use the server application you have written. Cloud Events provides SDKs for Go, JavaScript, Java, C#, Ruby, PHP, PowerShell, Rust, and Python.

Server SDK Setup

The server should provide an HTTPS endpoint that can accept a POST, and the URI will be /functions.

{% swagger method="post" path="/functions" baseUrl="https://api.apexfunctions.com" summary="Start a function by posting data to this URL" expanded="false" %} {% swagger-description %}

{% endswagger-description %} {% endswagger %}

{% swagger method="get" path="/functions" baseUrl="https://api.apexfunctions.com" summary="Get details about running functions and performance metrics. " %} {% swagger-description %} (Need to define a JSON Format) {% endswagger-description %}

{% swagger-parameter in="body" %}

{% endswagger-parameter %} {% endswagger %}

Function Class\

Use the Function Apex class to access deployed Salesforce Functions and invoke them synchronously or asynchronously.

This is the primary class all users will use. The sample code will look as follows. 

public static string FunctionDemo() {
  Function accountFunction = Function.get('MyProject.AccountFunction');
  FunctionInvocation invocation = accountFunction.invoke('{"AccountId":"123"}');
  return invocation.getResponse();     
}

Note the line Function.get('MyProject.AccountFunction'); The value we are passing MyProject.AccountFunction.

MyProject is the name of the named credential if the URL is set to https://api.apexfunctions.com/ in a named credential called "MyProject" The callout will look like

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:MyProject/AccountFunction');
req.setMethod('POST');
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());

AccountFunction is the name of the function that is passed to the server.

Request JSON (Work in Progress)

{
  "userSessionId" : "SESSION_ID_REMOVED",
  "userName" : "apexfunctions@demo.com",
  "type" : "AccountFunction",
  "timeStamp" : "4/29/2023, 11:02:21 AM PDT",
  "specversion" : "1.0",
  "source" : "https://server.develop.my.salesforce.com",
  "orgId" : "00DDo000001AEWSMA5",
  "id" : "01GZ72W7GFRMQDYCHM6ZZ9C0D1",
  "datacontenttype" : "application/json",
  "data_base64" : null,
  "data" : "{\"AccountId\":\"123\"}"
}
JSON PropertyDescription
userSessionId
userName
type
timeStamp
specversion
source
orgId
id
datacontenttype
data_base64Do we need this ?
data

Response JSON (Work in Progress)

{
  "userName" : "apexfunctions@demo.com",
  "totalTime" : 123,
  "timeCompleted" : "2023-04-29T18:02:21.598Z",
  "serverName" : "Azure Lambada Server One",
  "source" : "https://server.develop.my.salesforce.com",
  "response" : "{\"AccountId\":\"123\"}",
  "orgId" : "00DDo000001AEWSMA5",
  "invocationStatus" : "SUCCESS",
  "invocation":"01GZ72W7GFRMQDYCHM6ZZ9C0D1",
  "function":"AccountFunction",
  "error" : "
}
JSON PropertyDescription
userName
totalTime
timeCompleted
serverName
source
orgId
invocationidThis should be id but that is a reserved word in SF
function
error
response

Call Backs

SF Function can be invoked asynchronously. For this, the calling Apex Code will implement

  • FunctionCallback Interface
    Represents the callback Salesforce calls when an asynchronous, queued Function invocation has been completed.

The following sample code shows how this is done in Apex

public static string FunctionCallBackDemo() {
  Function accountFunction = Function.get('MyProject.AccountFunction');
  FunctionInvocation invocation = accountFunction.invoke('{"AccountId":"123"}', new DemoCallBack);
  return invocation.getResponse();     
}

public class DemoCallback
  implements functions.FunctionCallback {
    public void handleResponse(functions.FunctionInvocation result) {
      // Handle the result of function invocation
      String jsonResponse = result.getResponse();
      System.debug('Got response ' + jsonResponse);
      JSONParser parser = JSON.createParser(jsonResponse);
    }
}

1:1 Callbacks: These are callbacks when a request is completed

1:N Callbacks: These are callbacks that are made during the execution of a function.

Server side SDK

Salesforce object name

Field NameTypeComment
NameStringThe ID of the function call
StatusStringERROR, PENDING, SUCCESS
ResponseStringResponse as a JSON Striong
ResponseTypeStringJSON or Base64
CallBackClassStringThe name of the Apex Callback Class