External API Request

The external API request function allows you to access and process an external API endpoint from 3rd party services. This enables your backend to interact with other APIs, which can be integrations with other SaaS products or any other custom APIs.

Typically, the external API that you wish to interact with will come with API documentation from the provider. It is paramount that you read and understand the provided API documentation because this will explain how to set up and call the API endpoint successfully. The more you familiarize yourself with APIs from different providers, the more you will see that each requires a different and specific set up (parameters, schema, methods, headers, authentication, etc.).

There are several parts to the external API request function:

Import CURL: Allows you to import the cURL command of an external API endpoint. Xano can automatically build the API request when the cURL command is imported.

URL: is the request URL of the API endpoint. (example: https://api.example.com/v1/)

Method: the verb that is used for the endpoint (GET, POST, PUT, DELETE, etc.)

Params: are the parameters that are passed into the API, these can be Path parameters or Query parameters. Headers: are the parameters that allow you to define custom request headers.

Timeout: How long should Xano wait in seconds for a response before considering the request timed out. The default is 10, but you can adjust this as needed depending on the external API you are calling. The maximum time supported is one hour, or 3600 seconds.

Follow_location: determines if you wish to automatically follow the redirects (if there are any) in the API call. (An example of this would be an API that generates a file for you, then gives you a redirect to get that file. Google does this when turning a spreadsheet into a CSV).

The external API request function has several different parts to it.

Building an external API request: two ways

Import CURL

The Import CURL button is a powerful tool that helps save a huge amount of time when creating external API requests. Often times, API documentation will provide a CURL command of the API call. This can be copied and pasted into Xano to automatically build the formatted call to the external API.

In this example, we are going to use the public documentation of the Sendgrid API.

curl --request POST \
--url https://api.sendgrid.com/v3/mail/send \
--header 'Authorization: Bearer <<YOUR_API_KEY>>' \
--header 'Content-Type: application/json' \
--data '{"personalizations":[{"to":[{"email":"[e-mail]","name":"John Doe"}],"subject":"Hello, World!"}],"content": [{"type": "text/plain", "value": "Heya!"}],"from":{"email":"[e-mail]","name":"Sam Smith"},"reply_to":{"email":"[e-mail]","name":"Sam Smith"}}'

First, copy the curl command.

Then, open the external API request function in Xano and select the import curl button. Paste in the curl command and select import.

The curl command is pasted in.

After importing the curl, Xano creates the external API request by programmatically exploding out the content.

The import curl functionality is a huge time saver by cutting down the time it would take to enter all this information in manually.

The import curl functionality saves a massive amount of time by not having to enter all the information manually.

With the quickly built API call to Sendgrid, we can now swap out any values we may need to with dynamic inputs or variables.

Manually Build an External API Request

A curl command will not always be provided by the external service's API documentation. Therefore, sometimes manually building the external API request is required. Fortunately, Xano still makes this easy to do with the external API request function.

To examine this, let's breakdown each component of the function:

URL: is the request URL of the API endpoint. (example: https://api.example.com/v1/)

The API endpoint URL goes directly in the input box as text. Filters are also available in case you need to add any text or data manipulation to the URL. (Commonly used ones include sprintf, concat, url_addarg).

The API endpoint URL goes directly into the input box

Method: the verb that is used for the endpoint (GET, POST, PUT, DELETE, etc.)

Open the drop down selector to choose from all the potential method values for an API call. They include: GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH.

Use the drop down to select which method to use for the external API call.

Params: are the parameters that are passed into the API, these can be Path parameters or Query parameters.

Parameters are typically defined with a key value pairing. Notice that the data type is defaulted to an object. You can use the quick filter SET to build the path or key and add the related value. (Note: values can often be dynamic with inputs or variables).

Note: When referencing the API documentation of the provider pay attention to if they define acceptable values for each parameter.

SET allows you to quickly add a parameter.

The SET filter:

The path would be considered the parameter name or key. The value is the value.

If provided a request body, you can use the IMPORT JSON functionality to paste the request body into the parameter section and import it. This will work similarly to import curl but is used for just the request body.

You can either open the drop down and find the import JSON option or paste the request body directly in the input box and Xano will detect it is JSON - from there you can select import.

Import JSON is an easy way to create the parameters if the request body is provided.

Headers: are the parameters that allow you to define custom request headers.

External APIs may often require headers according to the provider's API documentation. Often times, these may include different authentication methods where you may be required to define an API key or API secret that you receive from the external service.

To define a header, you can use the quick filter PUSH.

Use the quick filter PUSH to define a header.

The PUSH filter:

Add the header directly into the value section.

Follow_location: determines if you wish to automatically follow the redirects (if there are any) in the API call.

Follow_location has two potential values: True - if you want to automatically follow any redirects from the API call. False- if you do not want to follow any redirects from the API call.

Choose either a true boolean or false boolean.

Security Tab

The security tab allows you to define specific rules in regards to SSL validation for the API being called. It is likely that you will not have to ever touch these options, so if you aren't sure if you should do anything here, the answer is most likely 'no'.

verify_host

Specify whether or not Xano should validate that the requested host matches the SSL certificate

verify_peer

This option enforces that the SSL certificate is genuine and verified to be from a trusted authority

ca_certificate

In this section, you can include your own CA certificate to assist with the peer verification step

Multipart Support

Xano has support for sending images through the external API request function. You can send a file resource - either as an input or variable - through the parameters section of the external API request as a key-value pair or as the entire parameter (depending on what the specific API requires).

Below is an example of sending an image as a key-value pair parameter to an external API. In this example, the image is being passed as a file resource input. They parameter key is named content and the value is the input.

An example of passing an image as a parameter to an external API.

Another example shows the file resource being created from a variable then being used in the parameters section.

In this example, the file resource is created from a variable.

In this last example, this particular external API requires the image to be sent as the entire parameter - versus in a key-value format. Below the file resource is created from a variable and the return variable is inserted into the params sections.

In this example, the image is sent as the entire parameter to the external API.

Calling a GraphQL API in Xano

Frequently Asked Questions

Result: False / Status: 0

This indicates that the external API did not respond in time. To resolve this, increase the timeout parameter in the external API request.