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.

Our API Connection Tooling is low-code tooling designed to be used by developers and other technical users. We also have a code-based API Connection tool that allows you to create API Connections using javascript code for advanced use cases.

Understanding API Connections

API Connections are the bridge between your GenerativeAgent and your external APIs. They allow your agent to interact with your existing systems and services, just like a human agent would.

How API Connections Fit In

GenerativeAgent uses a hierarchical structure to organize its capabilities:

1. Tasks: High-level instructions that tell GenerativeAgent what to do. A task can have one or more functions.
2. Functions: Tools that help GenerativeAgent complete tasks. A function can point to a single API Connection.
3. API Connections: Configurations that enable Functions to interact with your APIs.

Core Components

Each API Connection consists of three main parts that work together:

1. API Source:

   • Handles the technical details of calling your API
   • Manages authentication and security
   • Configures environment-specific settings (sandbox/production)

2. Request Interface:

   • Defines what information GenerativeAgent can send
   • Transforms GenerativeAgent’s requests into your API’s format
   • Includes testing tools to verify the transformation

3. Response Interface:

   • Controls what data GenerativeAgent receives
   • Transforms the API response to a GenerativeAgent friendly format
   • Includes testing tools to verify the transformation

Create an API Connection

To create an API Connection, you need to:

We have a code-based API Connection tool that allows you to create API Connections using javascript code. This is for advanced use cases such as where you need to merge multiple APIs into a single API Connection.

1. Access the API Integration Hub

   1. Navigate to API Integration Hub in your dashboard
   2. Select the API Connections tab
   3. Click the Create Connection button
2. 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.

3. 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.

4. Configure the API Source

   After creation, you’ll be taken to the API Source configuration page. Here you’ll need to:

   1. Set up authentication methods
   2. Configure environment settings
   3. Define error handling rules
   4. Add any required static headers
5. Set Up Request and Response Interfaces

   Configure how GenerativeAgent interacts with your API:

   1. Define the Request Interface:
      • Specify the schema GenerativeAgent will use
      • Create request transformations
      • Test with sample requests
   2. Configure the Response Interface:
      • Define the response schema
      • Set up response transformations
      • Validate with sample responses
6. Test and Validate

   Before finalizing your API Connection:

   1. Run test requests in the sandbox environment
   2. Verify transformations work as expected
   3. Check error handling behavior
7. 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

Simplify Field Names

// Good - Clear and descriptive
{
  "type": "object",
  "properties": {
    "customer_name": {
      "type": "string"
    },
    "order_date": {
      "type": "string"
    }
  }
}

// Avoid - Cryptic or complex
{
  "type": "object", 
  "properties": {
    "cust_nm_001": {
      "type": "string"
    },
    "ord_dt_timestamp": {
      "type": "string"
    }
  }
}

Flatten Complex Structures

// Good - Flat structure
{
  "type": "object",
  "properties": {
    "shipping_street": {
      "type": "string"
    },
    "shipping_city": {
      "type": "string"
    },
    "shipping_country": {
      "type": "string"
    }
  }
}

// Avoid - Deep nesting
{
  "type": "object",
  "properties": {
    "shipping": {
      "type": "object",
      "properties": {
        "address": {
          "type": "object",
          "properties": {
            "street": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "country": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Add Clear Descriptions

{
  "properties": {
    "order_status": {
      "type": "string",
      "description": "Current status of the order (pending, shipped, delivered)",
      "enum": ["pending", "shipped", "delivered"]
    }
  }
}

Remove Optional Fields

• Keep only essential fields that GenerativeAgent needs
• Set "additionalProperties": false to prevent unexpected data

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.

You can use the built in JSONata functions to transform the data.

When first created, the Request Transformation is a 1-1 mapping to the underlying API spec.

Transformation Input

The response transformation is passed the following variables:

• request: The request object provided by GenerativeAgent. This will match your defined schema.

• context: The context object passed in by the ASAPP system. This currently contains the following values:

  • externalConversationId: The id of the conversation as provided by your system when creating the conversation.
  • asapp.conversationId: The id of the conversation as generated by ASAPP.
  Example Context JSON

  {
    "externalConversationId": "123",
    "asapp":{
      "conversationId": "456"
    }
  }
  

These values are available to the transformation as context.[value] and request.[value].

Common Transformation Patterns

Basic Field Mapping

{
  "headers": {
    "Content-Type": "application/json"
  },
  "pathParameters": {
    "userId": request.id
  },
  "queryParameters": {
    "include": "details,preferences"
  },
  "body": {
    "name": request.userName,
    "email": request.userEmail
  }
}

Data Formatting

{
  "body": {
    // Convert date to ISO format
    "timestamp": $toMillis(request.date),
    // Uppercase a value
    "region": $uppercase(request.country),
    // Join array values
    "tags": $join(request.categories, ",")
  }
}

Conditional Logic

{
  "body": {
    // Include field only if present
    "optional_field": $exists(request.someField) ? request.someField : undefined,
    // Transform based on condition
    "status": request.isActive = true ? "ACTIVE" : "INACTIVE"
  }
}

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

Test Various Scenarios

// Test 1: Minimal valid request
{
  "customerId": "123",
  "action": "view"
}

// Test 2: Full request with all fields
{
  "customerId": "123",
  "action": "update",
  "data": {
    "name": "John Doe",
    "email": "[e-mail]"
  }
}

Validate Error Cases

• Test with missing required fields
• Verify invalid data handling
• Check boundary conditions

Use Sandbox Environment

By Default, the API Connection testing is local. You can test against actual API endpoints by setting “Run test in” to Sandbox.

• Test against actual API endpoints
• Verify complete request flow
• Check response handling

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

Focus on Essential Data

// Good - Only relevant fields
{
  "orderStatus": "shipped",
  "estimatedDelivery": "2024-03-20",
  "trackingNumber": "1Z999AA1234567890"
}

// Avoid - Including unnecessary details
{
  "orderStatus": "shipped",
  "estimatedDelivery": "2024-03-20",
  "trackingNumber": "1Z999AA1234567890",
  "internalId": "ord_123",
  "systemMetadata": { /* ... */ },
  "auditLog": [ /* ... */ ]
}

Use Clear Data Types

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "Current temperature in Celsius"
    },
    "isOpen": {
      "type": "boolean",
      "description": "Whether the store is currently open"
    },
    "lastUpdated": {
      "type": "string",
      "format": "date-time",
      "description": "When this information was last updated"
    }
  }
}

Standardize Formats

• Use consistent date/time formats
• Normalize enumerated values
• Use standard units of measurement

When first created, the Response Schema is a 1-1 mapping to the underlying API spec.

Response Transformation

The Response Transformation converts the raw API response into the format GenerativeAgent will receive. This is done using JSONata expressions.

GenerativeAgent works best with simple, structured data. The goal is to simplify and standardize the data.

You can use the built in JSONata functions to transform the data.

When first created, the Response Transformation is a 1-1 mapping to the underlying API spec.

Transformation Input

The response transformation is passed the following variables:

• clientApiCall.data: The raw JSON response from the API.

This value is available to the transformation as clientApiCall.data.

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

Test Different Response Types

Make sure to test with different response types your server may respond with.

This should include happy paths, varied response types, and error paths.

Validate Data Formatting

• Check date/time formatting
• Verify numeric calculations
• Test string manipulations

Edge Cases

• Handle null/undefined values
• Process empty arrays/objects
• Manage missing optional fields

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:

1. Navigate to API Integration Hub > API Specs
2. Click on the relevant API Spec.
3. Click on the “Parameters” tab and flag
4. 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.

Update Passenger Name (Simple mapping)

This example demonstrates configuring an API connection for updating a passenger’s name on a flight booking.

API Endpoint

PUT /flight/[flightId]/passenger/[passengerId]
{
  "name": {
    "first": [Passenger FirstName],
    "last": [Passenger LastName]
  }
}

API Response

{
  "id": "pax-12345",
  "flightId": "XZ2468",
  "updatedAt": "2024-10-04T14:30:00Z",
  "passenger": {
    "id": "PSGR-56789",
    "name": {
      "first": "John",
      "last": "Doe"
    },
    "seatAssignment": "14A",
    "checkedIn": true,
    "frequentFlyerNumber": "FF123456"
  },
  "status": "confirmed",
  "specialRequests": ["wheelchair", "vegetarian_meal"],
  "baggage": {
    "checkedBags": 1,
    "carryOn": 1
  }
}

Request Configuration

1. Request Schema:

{
  "type": "object",
  "properties": {
    "externalCustomerId": {"type": "string"},
    "passengerFirstName": {"type": "string"},
    "passengerLastName": {"type": "string"},
    "flightId": {"type": "string"}
  },
  "required": ["externalCustomerId", "passengerFirstName", "passengerLastName", "flightId"]
}

2. Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "flightId": request.flightId,
    "passengerId": request.externalCustomerId
  },
  "queryParameters": {},
  "body": {
    "name": {
      "first": request.passengerFirstName,
      "last": request.passengerLastName
    }
  }
}

3. Sample Test Request:

{
  "externalCustomerId": "CUST123",
  "passengerFirstName": "Johnson",
  "passengerLastName": "Doe",
  "flightId": "XZ2468"
}

Response Configuration

1. Response Schema:

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the name update was successful"
    }
  },
  "required": ["success"]
}

2. Response Transformation:

{
  "success": $exists(clientApiCall.data.id) and 
            $exists(clientApiCall.data.passenger.name.first) and 
            $exists(clientApiCall.data.passenger.name.last) and 
            clientApiCall.data.status = "confirmed"
}

3. Sample Test Response:

{
  "clientApiCall": {
    "data": {
      "id": "pax-12345",
      "flightId": "XZ2468",
      "updatedAt": "2024-10-04T14:30:00Z",
      "passenger": {
        "id": "PSGR-56789",
        "name": {
          "first": "John",
          "last": "Doe"
        },
        "seatAssignment": "14A",
        "checkedIn": true,
        "frequentFlyerNumber": "FF123456"
      },
      "status": "confirmed",
      "specialRequests": ["wheelchair", "vegetarian_meal"],
      "baggage": {
        "checkedBags": 1,
        "carryOn": 1
      }
    }
  }
}

Lookup Flight Status (Complex mapping)

This example shows how to simplify a complex flight status API response by removing unnecessary fields and flattening nested structures.

API Endpoint

GET /flights/[flightNumber]/status

API Response

{
  "flightDetails": {
    "flightNumber": "AA123",
    "route": {
      "origin": {
        "code": "SFO",
        "terminal": "2",
        "gate": "A12",
        "weather": { /* complex weather object */ }
      },
      "destination": {
        "code": "JFK",
        "terminal": "4",
        "gate": "B34",
        "weather": { /* complex weather object */ }
      }
    },
    "schedule": {
      "departure": {
        "scheduled": "2024-03-15T10:30:00Z",
        "estimated": "2024-03-15T10:45:00Z",
        "actual": null
      },
      "arrival": {
        "scheduled": "2024-03-15T19:30:00Z",
        "estimated": "2024-03-15T19:45:00Z",
        "actual": null
      }
    },
    "status": "DELAYED",
    "aircraft": { /* aircraft details */ }
  }
}

Request Configuration

1. Request Schema:

{
  "type": "object",
  "properties": {
    "flightNumber": {
      "type": "string",
      "description": "The flight number to look up"
    }
  },
  "required": ["flightNumber"]
}

2. Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "flightNumber": request.flightNumber
  },
  "queryParameters": {},
  "body": {}
}

3. Sample Test Request:

{
  "flightNumber": "AA123"
}

Response Configuration

1. Response Schema:

{
  "type": "object",
  "properties": {
    "flight_number": { 
      "type": "string",
      "description": "The flight number"
    },
    "flight_status": { 
      "type": "string",
      "description": "Current status of the flight"
    },
    "origin_airport_code": { 
      "type": "string",
      "description": "Three-letter airport code for origin"
    },
    "destination_airport_code": { 
      "type": "string",
      "description": "Three-letter airport code for destination"
    },
    "scheduled_departure_time": { 
      "type": "string",
      "description": "Scheduled departure time"
    },
    "scheduled_arrival_time": { 
      "type": "string",
      "description": "Scheduled arrival time"
    },
    "is_flight_delayed": { 
      "type": "boolean",
      "description": "Whether the flight is delayed"
    }
  }
}

2. Response Transformation:

{
  "flight_number": clientApiCall.data.flightDetails.flightNumber,
  "flight_status": clientApiCall.data.flightDetails.status,
  "origin_airport_code": clientApiCall.data.flightDetails.route.origin.code,
  "destination_airport_code": clientApiCall.data.flightDetails.route.destination.code,
  "scheduled_departure_time": clientApiCall.data.flightDetails.schedule.departure.estimated,
  "scheduled_arrival_time": clientApiCall.data.flightDetails.schedule.arrival.estimated,
  "is_flight_delayed": clientApiCall.data.flightDetails.status = "DELAYED"
}

Appointment Lookup (Date Formatting)

This example demonstrates date formatting and complex object transformation for an appointment lookup API.

API Endpoint

GET /appointments/[appointmentId]

API Response

{
  "id": "apt_123",
  "type": "DENTAL_CLEANING",
  "startTime": "2024-03-15T14:30:00Z",
  "endTime": "2024-03-15T15:30:00Z",
  "provider": "Dr. Sarah Smith",
  "location": "Downtown Medical Center",
  "patient": {
    "id": "pat_456",
    "name": "John Doe",
    "dateOfBirth": "1985-06-15",
    "contactInfo": {
      "email": "[e-mail]",
      "phone": "[phone]"
    }
  },
  "status": "confirmed",
  "notes": "Regular cleaning and check-up",
  "insuranceVerified": true,
  "lastUpdated": "2024-03-01T10:15:00Z"
}

Request Configuration

1. Request Schema:

{
  "type": "object",
  "properties": {
    "appointmentId": {
      "type": "string",
      "description": "The ID of the appointment to look up"
    }
  },
  "required": ["appointmentId"]
}

2. Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "appointmentId": request.appointmentId
  },
  "queryParameters": {},
  "body": {}
}

3. Sample Test Request:

{
  "appointmentId": "apt_123"
}

Response Configuration

1. Response Schema:

{
  "type": "object",
  "properties": {
    "appointmentType": { 
      "type": "string",
      "description": "The type of appointment in a readable format"
    },
    "date": { 
      "type": "string",
      "description": "The appointment date in a friendly format"
    },
    "startTime": { 
      "type": "string",
      "description": "The appointment start time in 12-hour format"
    },
    "doctor": { 
      "type": "string",
      "description": "The healthcare provider's name"
    },
    "clinic": { 
      "type": "string",
      "description": "The location where the appointment will take place"
    },
    "status": {
      "type": "string",
      "description": "The current status of the appointment"
    },
    "patientName": {
      "type": "string",
      "description": "The name of the patient"
    }
  },
  "required": ["appointmentType", "date", "startTime", "doctor", "clinic", "status", "patientName"]
}

2. Response Transformation:

{
  /* Convert appointment type from UPPER_SNAKE_CASE to readable format */
  "appointmentType": $replace(clientApiCall.data.type, "_", " ") ~> $lowercase(),
  
  /* Format date as "Friday, March 15th, 2024" */
  "date": $fromMillis($toMillis(clientApiCall.data.startTime), "[FNn], [MNn] [D1o], [Y]"),
  
  /* Format start time as "2:30 PM" */
  "startTime": $fromMillis($toMillis(clientApiCall.data.startTime), "[h]:[m01] [P]"),
              
  /* Map provider and location directly */
  "doctor": clientApiCall.data.provider,
  "clinic": clientApiCall.data.location,
  
  /* Map status and patient name */
  "status": clientApiCall.data.status,
  "patientName": clientApiCall.data.patient.name
}

3. Sample Transformed Response:

{
  "appointmentType": "dental cleaning",
  "date": "Friday, March 15th, 2024",
  "startTime": "2:30 PM",
  "doctor": "Dr. Sarah Smith",
  "clinic": "Downtown Medical Center",
  "status": "confirmed",
  "patientName": "John Doe"
}

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:

Previewer

Integrating GenerativeAgent

Connecting Your Knowledge Base