API-Based Embedding
Last update: 21.11.2023
API-Based Embedding
API based embedding enables our clients to seamlessly embed APIFuse workflow capabilities into their own SaaS products.
Broadly APIs are categorized into Connection APIs, Connector APIs & Workflow APIs.
Connection APIs let you handle user authentication for third-party applications, such as Salesforce, Quickbooks, etc.
Connector APIs let you fetch all the connectors, triggers & actions available for your account.
Workflow APIs provide all the interfaces necessary to build your own Workflow/Integration builder.
APIs are secured using JWT tokens. You need to generate a JWT token for your end user to access API endpoints.
Generating a JWT bearer token:
To generate an APIFuse JWT token, you need to create a user JWT token as described in the documentation https://docs.apifuse.io/user-authentication/, then you can exchange the user token for an APIFuse JWT token.
Sample curl call is given below for exchanging user JWT token for APIFuse JWT token.
curl –location –request POST ‘https://api.apifuse.io/auth/customer/login‘ \
–header ‘Content-Type: application/json’ \
–data-raw ‘{
“token”:”eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdJZCI6IjEyMjMyMzIiLCJ1c2VyIjp7ImV4dGVybmFsSWQiOiJ5b3VyX2N1c3RvbWVyX2lkIiwiZmlyc3RuYW1lIjoiYWJjIiwibGFzdG5hbWUiOiJ4eXoiLCJlbWFpbCI6ImFiY0B4eXouY29tIiwibW9uZXRpemF0aW9uUGxhbiI6ImZyZWVtaXVtIn0sImlhdCI6MTY2MDkwMzU5MX0.2DGzYYOiL15kTMOSUvCH-xaMSo552BWmEBi_JM4lFEY”
}‘
Response:
{ “status”: “success”, “message”: “”, “token“: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjA5NDY4MTUsInVzZXJJZCI6IjExMTExMS0xMTExMS00NTkyLTg0NmUtMTExMTExIiwic3ViIjoiMTExMTExLTExMTExLTQ1OTItODQ2ZS0xMTExMTEiLCJlbWFpbCI6ImFiY0B4eXouY29tIiwib3JnSWQiOiIxMjM0NTY3ODkiLCJyb2xlIjoiT1JHX0NVU1RPTUVSIiwib3JnUm9sZSI6bnVsbCwibW9uZXRpemF0aW9uUGxhbiI6ImZyZWVtaXVtIiwiZmVhdHVyZXMiOm51bGwsImlzU3VkbyI6ZmFsc2UsIm9yZ0FkbWluVXNlciI6bnVsbCwiYWRtaW5Vc2VyIjpudWxsLCJjb25uZWN0aW9uIjpudWxsLCJvcmdDb25uZWN0b3IiOiJhcHAtdjEiLCJpYXQiOjE2NjA5MDM2MTV9.gYS2LTT2JZMQUruprIv2slTuBaYEihJoG6Mo5Bbx7dM” }
APIFuse API Specification.docx
Workflow Code
Workflow code is a set of instructions in JSON format that instructs the APIFuse integration processor on triggering an event and acting upon the triggered event.
The following JSON represents the basic structure of the workflow code:
{
“workflowName”: “”,
“steps”: [],
“trigger”: {
“stepId”: “”,
“triggerType”: “”
}
}
workflowName – (string) A free text field to provide a unique name for the workflow.
steps – (array) An array of steps containing all the steps executed as part of a workflow, including triggers and actions.
trigger – Trigger configuration specifying which step is a trigger step ( from the list of steps in the above steps array)
Trigger
Step Object
The step JSON object represents the step configuration in the workflow builder UI (https://docs.apifuse.io/configuring-a-trigger/). Steps can be triggers, actions or functions. Below are the common step object configurations.
stepId – (string) Unique identifier for the step within the workflow (preferably a GUID).
stepType – (object) Instructs the workflow processor on which connector to use for execution.Details can be retrieved from the connector API.
connectionId – (string) The Connection ID obtained from connection API. You need to pass the connection ID of the application you are using in the stepType.
nextStepId – (string) Defines the next step to be executed after the current step execution completed.
Schema – (object) Defines the input & output schema of the current step. APIFuse uses schema to parse the stepConfig & produce the output. Every connector triggers/actions have their own input and output schema. Connector schema should be dynamically fetched at the run time using Schema API.
stepConfig – (object) Input mapping fields. This object configuration depends on the step type, application and action type. Inputs fields that needed for current step are defined in the schema.
stepImports – (array) Some steps may be depend on the output of the previously executed steps. Include the stepIds that the current step depends on.
{
“stepId”: “3d5c2f8b-d044-487b-b01f-7949fd4cd236”,
“stepType”: {
“application”: “hubspot-v1”,
“appVersion”: 1,
“isFunction”: false,
“connectionRequired”: true,
“runtime”: “legacy”,
“typeId”: “trigger hubspot contact add”
},
“stepImports”: [ ],
“stepConfig”: {
“conditionTrigger”: []
},
“connectionId”: “abcdefg-11111-1111-1111-abcdefg”,
“nextStepId”: “eb60b395-6615-4427-9a9b-3be069905cc9”,
“schema”: {
“input”: [],
“output”: {}
}
}
Schema Objects
Schema objects define the inputs needed for a step to successfully execute and what will be produced after successful execution.
The below example shows the hubspot trigger input/output schema.
{
“input”: [
{
“name”: “properties”,
“displayName”: “Properties Required”,
“description”: “Select Properties”,
“controlType”: “multiselect”,
“extendedSchema”: “true”,
“type”: “TEXT”,
“dynamic”: “true”,
“picklistValue”: null,
“pickList”: “hubspot_properties_picklist”,
“linkedPickList”: {}
}
],
“output”: {
“contact”: {
“name”: “contact”,
“displayName”: “contact”,
“type”: “OBJECT”,
“value”: {
“id”: {
“name”: “id”,
“displayName”: “id”,
“type”: “TEXT”,
“value”: “”
},
“createdAt”: {
“name”: “createdAt”,
“displayName”: “createdAt”,
“type”: “TEXT”,
“value”: “”
},
“updatedAt”: {
“name”: “updatedAt”,
“displayName”: “updatedAt”,
“type”: “TEXT”,
“value”: “”
},
“firstname”: {
“name”: “firstname”,
“displayName”: “firstname”,
“type”: “TEXT”,
“value”: “”
},
“lastname”: {
“name”: “lastname”,
“displayName”: “lastname”,
“type”: “TEXT”,
“value”: “”
}
}
}
}
}
Input Schema
Input schema defines
name – (string) Name of the input field. stepConfig should include this name
displayName – (string) Name to display on the workflow builder UI.
type – (enum) Input field type. Valid values are TEXT, NUMBER INTEGER, OBJECT, LIST, FILE, DATETIME.
controlType – (enum) Control type defines how to render the input field in the UI. For example you can render the input field as a text box or dropdown based on controlType value. Text box is the default render type. Valid values are select, multiselect, schema
extendedSchema – (boolean) In some cases, the entire input schema cannot be obtained in a single extended API call. For example, in the case of the Google Sheet connector, only after selecting the file name, sheet information can be retrieved. Similarly, only after selecting the sheet, columns for input can be retrieved. For such input fields, if the flag is enabled, the system will re-render the UI based on the selected value.
required – (boolean) if true, the input field is mandatory.
dynamic – (boolean) This field is used only if the control type is select or multiselect. This field indicates if the dropdown list value should be dynamically fetched.
picklistValue – (object) This field is used only if the control type is select or multiselect. It provides the list of values to display in the dropdown. This is a static list.
picklist – (string) If the dropdown list is dynamic, this field provides the name using which you can fetch the dynamic list of values for the dropdown.
Sample Multi Select field for the input schema object given above.
Ouput Schema
APIFuse uses output schema to produce the step output. You can use the output schema for field mapping. The image below illustrates APIFuse workflow builder input mapping. APIFuse builder uses output schema to display available fields for input field mapping ( Hubspot output fields shown on the right side).
The JSON schema below corresponds to the mapping fields shown in the screenshot above.
“output”: {
“contact”: {
“name”: “contact”,
“displayName”: “contact”,
“type”: “OBJECT”,
“value”: {
“id”: {
“name”: “id”,
“displayName”: “id”,
“type”: “TEXT”,
“value”: “”
},
“createdAt”: {
“name”: “createdAt”,
“displayName”: “createdAt”,
“type”: “TEXT”,
“value”: “”
},
“updatedAt”: {
“name”: “updatedAt”,
“displayName”: “updatedAt”,
“type”: “TEXT”,
“value”: “”
},
“firstname”: {
“name”: “firstname”,
“displayName”: “firstname”,
“type”: “TEXT”,
“value”: “”
},
“lastname”: {
“name”: “lastname”,
“displayName”: “lastname”,
“type”: “TEXT”,
“value”: “”
}
}
}
}
