Custom Code API Connections
Create custom API connections using JavaScript code
Code-based API connections allow you to create custom integrations with any external API using JavaScript. This enables you to support any authentication flow or API structure that your external systems require.
You will implement a function that takes a request as input and returns the response that will be sent to the GenerativeAgent. This allows you to transform data, handle complex authentication flows, and integrate with any external system.
Before You Begin
Before you begin, you will need:
-
An ASAPP Dashboard account with Edit permissions for Code based API Connections.
Your Admin should be able to enable this for you. Reach out to your ASAPP account team if you need help.
-
A basic understanding of JavaScript.
Using Code Based API Connections
Create initial Code API Connection
- Navigate to API Integration HUB > API Connections
- Click Create Connection
- Select Code-based API Connection from the dropdown
- Enter a Name and optional Description.
- Click Create connection
This creates a new, unimplemented API connection. You will be dropped into the Settings tab.
Set Up Allowed Domains
Code-based API connections are restricted to an explicit whitelist of domains as a security measure. You need to add each domain that your code will reach out to.
- In the Basic Settings tab, specify allowed domains for any API calls your code needs to make
- Click Add Domain and enter URLs (e.g.,
api.example.com
) - Wildcards (
*
) are supported for subdomains - Your code only calls URLs specified in the allowed domains using
asappUtilities.callAPI(url, apiRequest)
Manage Environment Variables
Store and manage environment variables to be used in your code. This is often used to store data that will change between environments, such as URLs for the API call you will be making.
Environment variables support storing Secret values which are encrypted when stored in the database. However, for API credentials and authentication data, we strongly recommend using Authentication Methods instead, as they provide better security and easier management.
- In the Environment Variables settings tab, add any variables your code needs.
- Specify the value for Sandbox and Production environments.
- Use the Secret checkbox to store encrypted environment variables (for configuration data, not API credentials)
- Access environment variables in your code using
asappUtilities.getEnvVariable("VARIABLE_NAME")
Add Authentication Methods
If your API connection requires authentication, add authentication methods to your API connection.
- Navigate to Settings → Authentication Methods
- For each environment, click Add Authentication to add a new authentication method.
- Create a new authentication method or select an existing one.
Define Request and Response Schemas
You need to define the structure of data that your API connection will receive and return:
- Request Schema (
schemas/request.json
) - Define the request schema that your function will receive - Response Schema (
schemas/response.json
) - Define the response schema that your function will return
See the Request Schema and Response Schema sections below for detailed information on how to structure these schemas.
Implement Your Function
Implement the handleRequest(request)
function in src/index.js
that takes the request object and returns the response object.
See the Implementing the Handle Function section below for detailed information on how to implement your function.
Test Your Code
As you write code, test it to ensure it works as expected:
- In the Run panel, define an example request that matches your
request.json
schema - Select which environment to run: Sandbox or Production
- Click Run
- Review the results in the left panel
You can not publish your code until you have successfully tested it.
Save and Deploy
Once you have successfully tested your API connection:
-
Publish the API connection. This will save your code and make it available as a new version.
There is not separate Save vs Publish functionality. You must directly publish any changes to your code.
-
It will now be available for use in your GenerativeAgent tasks and functions. If you have an existing function that uses this API connection, you will need to update it to use the new version.
-
Test the integration end-to-end to ensure it works as expected
Request Schema
The request schema (schemas/request.json
) defines the structure of data that your function will receive. This JSON schema is both the request schema that your function will receive and the parameters shown to GenerativeAgent.
Add the variables you want as input. Ensure the name and description of each variable is easy for GenerativeAgent to understand.
GenerativeAgent works better with flat JSON object as an input with a reduced number of properties. The more complex the input, the harder it is for GenerativeAgent to understand the request.
By default, the request schema is empty.
Example Request Schema
This example takes a last name and confirmation code as input for an airline rebooking function.
Response Schema
The response schema (schemas/response.json
) defines the structure of data that your function must return. This is the response that is shown to GenerativeAgent.
Add the variables you want as output. Ensure the name and description of each variable is easy for GenerativeAgent to understand.
GenerativeAgent can read complex JSON objects more effectively than on request. However, if you are seeing issues with GenerativeAgent not understanding the response, try reducing the number of properties in the response.
By default, the response schema is empty.
Example Response Schema
Implementing the Handle Function
The handleRequest(request)
function in src/index.js
is the core of your API connection. This function takes the request object and returns the response object.
When first created, your function looks like this:
Replace the NOT_IMPLEMENTED
error with your own implementation for the API connection.
Function Parameters
The request
parameter contains the data defined in your request schema.
Return Value
Your function should return an object that matches your response schema.
Error Handling
We expose several error classes in the asappUtilities
library. Always use one of these error classes for error handling to ensure proper error propagation to ASAPP:
ASAPP Utilities
ASAPP Utilities is a library designed for integration of Code Driven API Connections. It provides tools for writing secure and efficient code.
Making API Calls
The library provides a secure way to make API calls to allowed domains. This is the only way to make external HTTP API calls from your code.
Environment Variables
Access environment variables configured during setup. Use environment variables for configuration data like API URLs. Do not use environment variables for sensitive credentials.
For API credentials and authentication data, use Authentication Methods.
ASAPP Utilities Errors
In order to properly propagate errors to ASAPP, you must throw an asappUtilities
error:
asappUtilities.APIConnectionError
asappUtilities.APIConnectionError
This is a generic error that can be used to catch any error that occurs in your code.
asappUtilities.ClientAuthenticationError
asappUtilities.ClientAuthenticationError
This is an error that is thrown when a client authentication error occurs.
Raising this error will cause GenerativeAgent to send an authentication_required event to the client.
Context Data
When an API Connection is executed, there may be context data from the ASAPP system and this is available to you in the context
object.
Available Context Data
Available Context Data
This is the context data that is available to you in the context
object. Access it using dot notation.
Fetch Authentication Method Data
To use authentication methods for an API call, provide them as part of the request to asappUtilities.callAPI()
.
There may be times you want to pull out data from the authentication method, such grabbing claims from a JWT token. You can access the authentication methods you’ve configured in your code using the asappUtilities.getAuthMethod()
function.
Using Authentication Methods
Best Practice: Always use authentication methods instead of storing API keys in environment variables. Authentication methods provide better security, easier management, and support for complex authentication flows like OAuth, JWT, and custom token management.
If your API connection requires authentication, first you must add the authentcation method in Settings > Authentication Methods. Then, when making API calls with asappUtilities.callAPI()
, specify which authentication method to use by name for each environment:
The authMethods
object maps environment names to the exact names of your configured authentication methods. ASAPP automatically applies the appropriate authentication (e.g. tokens, api keys, etc.) to the headers based on the method you’ve configured for each environment.
Important: The authentication method names in your code must exactly match the names you gave them when creating the authentication methods in the Settings → Authentication Methods section.
Running your code
While developing your code-based API connection, you can test it by running it in the Run panel. This will allow you to test your code without having to publish it. Any console.log
statements will be displayed in the Run panel.
To specify the data that will be passed to your function when running, in the right hand run panel, you need to specify:
- The Request object that will be passed to your function. This must match the
request.json
schema. - The Context object that will be passed to your function.
- The Auth object that will be passed to your function. This is only used if the authentication method you are using uses client authentication data.
Additionally, you can specify the Environment to run your code in in the Environment dropdown.
Examples
Simple API Call
Using JWT Claims from Authentication
Additional Libraries
Currently, code-based API connections support the core ASAPP Utilities library and does not allow use of third-party libraries e.g. using require()
or import
statements.
If you require additional third-party libraries or tools for your integration, reach out to your ASAPP account team to discuss your specific needs.