How to Set Up an API Request Function in Superinterface

API Request functions in Superinterface allow your assistant to connect directly with external APIs. This lets your assistant fetch data, send information, or interact with third-party services, making it more versatile and capable. Whether you want to retrieve weather forecasts, get stock prices, or connect to any web service, setting up an API Request function is the way to go.

In this guide, we’ll walk you through the steps to set up an API Request function in Superinterface. We'll also provide a specific example using the Pirate Translator API to show how you can set up a text translation function.

Create a new function.

Step One: Create a New Function

Create a new assistant or edit an existing one, then navigate to the Functions tab.

Click on New Function.

Choose API Request as the response type. This will set up the function to make requests to external APIs.

Step Two: Configure the Function

Now that you've selected API Request, you’ll need to provide details to customize how the assistant will interact with the external service.

1. URL

What It Does: This is the endpoint the assistant will send requests to. An endpoint is a specific address provided by the API service that handles requests.

Example: If you're connecting to the Pirate Translator API, your URL should be: https://api.funtranslations.com/translate/pirate.json.

Configure the function.

2. Method

Choose the Request Method: The correct HTTP method depends on how the API you’re integrating with is designed, and it can vary from one API to another. Always refer to the API’s documentation to understand which method you should use.

Here are the common HTTP methods and what they often represent:

GET: Typically used to retrieve data. This is the most common method for fetching information, like getting weather updates or reading data from a database.

POST: Often used to send data to the API. It can be used for creating new records, submitting forms, or passing more complex data.

PUT/PATCH: Generally used to update existing data.

PUT might replace an entire resource.

PATCH can make partial updates.

DELETE: Typically used to remove data, such as deleting a record or file.

How to Decide Which Method to Use:

Check the API Documentation: The documentation for the external API will specify which HTTP method to use for each type of request. For example, it might instruct you to use GET for retrieving data, while POST is for sending data.

Understand the Purpose of Your Request:

If you’re retrieving or fetching information (e.g., getting weather data, reading user details, fetching a list of items), you’ll often use GET.

If you’re sending new data to be processed (e.g., submitting a form, creating a new account), POST might be the method.

If you’re updating existing data (e.g., changing user settings, modifying a profile), you might use PUT or PATCH.

If you’re deleting data (e.g., removing a record or file), DELETE could be the appropriate choice.

Example:

For the Open-Meteo Weather API, we use GET because we’re requesting data (current weather) without needing to send any additional information in the request body. The URL might look like: https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current_weather=true

Always check the API’s documentation to confirm which method you should use and how the API expects you to structure your requests.

3. Body

How It Works: In Superinterface, the parameters you define in the OpenAPI function specification (which are filled by the assistant) will be automatically merged into the body of the request. This means that if you set up a function to accept parameters, like location, from the assistant, those values will be included in the body when making the API request.

When to Use It: The body is typically used with methods like POST and PUT, where data needs to be sent to the API. If your function requires the assistant to provide certain inputs, such as a location, these will be included as part of the request body.

Example:

{ "location": "New York", "unit": "metric" }

In this example, if you set up a function to accept location as a parameter from the assistant, and the assistant provides "New York," that value will be merged into the body, along with any other specified parameters. This allows the API request to include all necessary information to retrieve data or perform the required action.

Note: Always check the API’s documentation to ensure the parameters are structured correctly in the body, as different APIs may have specific requirements.

4. Headers

How It Works: Headers provide additional information to the API along with your request. In Superinterface, you can manually set up headers in the function configuration to include necessary details such as authentication tokens, content types, or specific API instructions. Unlike parameters in the body, headers are not dynamically filled by the assistant—whatever you set in the configuration will be sent with each request.

When to Use It: Headers are essential when an API requires specific details to process a request, such as:

Authentication: Many APIs need an authentication token or API key to verify who is making the request.

Content Type: Defines the format of the data being sent (e.g., application/json, application/x-www-form-urlencoded).

Custom Instructions: Some APIs might require custom headers for specific behaviors or actions.

Example:

{ "Content-Type": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" }

Note: Always refer to the API documentation to confirm what headers are required and how they should be structured. This ensures that your assistant’s requests are properly configured and accepted by the external service.

Step Three: Save the Function

After filling in all the details, click Save. Your function is now set up and ready for your assistant to use.

Example: Setting Up a Weather Data Retrieval Function with Open-Meteo

Let’s walk through an example using the Open-Meteo API, a free weather service that doesn’t require an API key.

Open-Meteo Example Configuration

URL: https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current_weather=true

Method: GET

Headers: Not needed for this example, as Open-Meteo does not require special headers.

Body: Not needed, since we are using GET to retrieve data.

Explanation:

The Open-Meteo API endpoint shown here retrieves the current weather for a location using latitude and longitude coordinates. In this example, it will return weather data for Berlin, Germany (latitude: 52.52, longitude: 13.41).

The response might look like this:

{ "current_weather": { "temperature": 15.3, "wind_speed": 11.2, "time": "2024-10-17T12:00" } } ### Ready to Publish? Your API Request function is now fully set up, and your assistant is ready to interact with external APIs. Once you’re satisfied with the configuration, it’s time to publish your assistant and make it available on your website. Simply click **Publish** to integrate your assistant with your site. For a step-by-step guide on how to publish, head over to [Publish Interface](/docs/interfaces/publish). Once published, your assistant will be live and ready to handle requests, bringing powerful API interactions directly to your users.