Connecting Your APIs
Learn how to connect your APIs to GenerativeAgent with API Connections
GenerativeAgent can call your APIs to get data or perform actions through API Connections. These connections allow GenerativeAgent to handle complex tasks like looking up account information or booking flights.
Our API Connection tooling lets you transform your existing APIs into LLM-friendly interfaces that GenerativeAgent can use effectively. Unlike other providers that require you to create new simplified APIs specifically for LLM use, ASAPP’s approach lets you leverage your current infrastructure without additional development work.
Typically, a developer or other technical user will create API Connections. If you need help, reach out to your ASAPP team.
Understanding API Connections
An API connection consists of three core components:
-
API Source:
- Defines how to call your API
- Handles authentication, headers, and error responses
- Configures environment-specific settings (sandbox/production)
-
Request Interface:
- Specifies what GenerativeAgent sees and can request
- Transforms GenerativeAgent’s requests into your API format
- Provides testing capabilities for validation
-
Response Interface:
- Controls what data GenerativeAgent receives back
- Transforms API responses into LLM-friendly formats
- Supports data formatting and simplification
Create an API Connections
To create an API Connection, you need to:
Access the API Integration Hub
- Navigate to API Integration Hub in your dashboard
- Select the API Connections tab
- Click the Create Connection button
Select or Upload Your API Specification
Every API Connection requires an OpenAPI specification that defines your API endpoints and structure.
- Choose an existing API spec from your previously uploaded API Specs, or
- Upload a new OpenAPI specification file
We support any API that uses JSON for requests and responses.
Configure Basic Details
Provide the essential information for your connection:
- Name: A descriptive name for the API Connection
- Description: Brief explanation of the connection’s purpose
- Endpoint: Select the specific API endpoint from your specification
Only endpoints with JSON request and response bodies are supported.
Configure the API Source
After creation, you’ll be taken to the API Source configuration page. Here you’ll need to:
- Set up authentication methods
- Configure environment settings
- Define error handling rules
- Add any required static headers
Set Up Request and Response Interfaces
Configure how GenerativeAgent interacts with your API:
- Define the Request Interface:
- Specify the schema GenerativeAgent will use
- Create request transformations
- Test with sample requests
- Configure the Response Interface:
- Define the response schema
- Set up response transformations
- Validate with sample responses
Test and Validate
Before finalizing your API Connection:
- Run test requests in the sandbox environment
- Verify transformations work as expected
- Check error handling behavior
Link to Functions
Once your API Connection is configured and tested, you can reference it in a Function to enable GenerativeAgent to use the API.
Request Interface
The Request Interface defines how GenerativeAgent interacts with your API. It consists of three key components that work together to enable effective API communication.
- Request Schema: The schema of the data that GenerativeAgent can send to your API.
- Request Transformation: The transformation that will apply to the data before sending it to your API.
- Testing Interface: The interface that allows you to test the request transformation with different inputs.
Request Schema
The Request Schema specifies the structure of data that GenerativeAgent can send to your API. This schema should be designed for optimal LLM interaction.
This schema is NOT the schema of the API. This is the schema of that is shown to GenerativeAgent.
Best Practices for Schema Design
When first created, the Request Schema is a 1-1 mapping to the underlying API spec.
Request Transformation
The Request Transformation converts GenerativeAgent’s request into the format your API expects. This is done using JSONata expressions.
When first created, the Request Transformation is a 1-1 mapping to the underlying API spec.
Common Transformation Patterns
Request Testing
Thoroughly test your request transformations to ensure GenerativeAgent can send the correct data to your API.
The API Connection can not be saved until the request transformation has a successful test.
Testing Best Practices
Response Interface
The Response Interface determines how API responses are processed and presented to GenerativeAgent. A well-designed response interface makes it easier for GenerativeAgent to understand and use the API’s data effectively.
There are three main components to the response interface:
- Response Schema: The JSON schema for the data returned to GenerativeAgent from the API.
- Response Transformation: A JSONata transformation where the API response is transformed into the response given to GenerativeAgent.
- Test Response: The testing panel to test the response transformation with different API responses and see the output.
Response Schema
The Response Schema defines the structure of data that GenerativeAgent will receive. Focus on creating clear, simple schemas that are optimized for LLM processing.
The Response Schema is NOT the schema of the underlying API. This is the schema of what is returned to GenerativeAgent.
Schema Design Principles
When first created, the Response Schema is a 1-1 mapping to the underlying API spec.
Response Transformation
Transform complex API responses into GenerativeAgent-friendly formats using JSONata. The goal is to simplify and standardize the data.
The Transformation’s input is the raw API response. The output is the data that GenerativeAgent will receive and must match the Response Schema.
When first created, the Response Transformation is a 1-1 mapping to the underlying API spec.
Transformation Examples
Response Testing
Thoroughly test your response transformations to ensure GenerativeAgent receives well-formatted, useful data.
The API Connection can not be saved until the response transformation has a successful test.
Use API Mock Users to save response from your server to use them in the response testing.
Testing Strategies
Redaction
You have the option to redact fields in the request or response from API Connection Logs or Conversation Explorer.
You can redact fields the internal request and response, by adding x-redact
to a field in the Request Schema or Response Schema. You will need to save the API connection to apply the changes. This will redact the fields in the Conversation Explorer as well.
You can redact fields in the raw API request and response, by flagging the fields in the relevant API Spec:
- Navigate to API Integration Hub > API Specs
- Click on the relevant API Spec.
- Click on the “Parameters” tab and flag
- Per endpoint, click the fields you want to redact.
Redacting the Spec will redact the fields within the API Connection Log.
API Versioning
Every update to an API Connection requires a version change. This is to ensure that no change can be made to an API connection that impacts a live function.
If you make a change to an API connection, the Function that references that API connection will need to be explicitly updated to point to the new version.
API Connection Logs
We log all requests and responses for API connections. This allows you to see the raw requests and responses, and the transformations that were applied.
Use the logs to debug and understand how API connections are working.
Logs are available in API Integration Hub > API Connection Logs.
Default API Spec Settings
You can set default information in an API spec. These default settings are used as a template for newly created API connections, copying those settings for all API connections created for that API spec.
You can set the following defaults:
- Headers
- Sandbox Settings:
- Base URL
- Authentication Method
- Production Settings:
- Base URL
- Authentication Method
You can make further changes to API connections as necessary.
You can also change the defaults and it will not change existing API connections, though the new defaults will be used on any new connections made with that Spec.
Examples
Here are some examples of how to configure API connections for different scenarios.
Next Steps
Now that you’ve configured your API connections, GenerativeAgent can interact with your APIs just like a live agent. Here are some helpful resources for next steps:
Was this page helpful?