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

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":"john.doe@example.com","name":"John Doe"}],"subject":"Hello, World!"}],"content": [{"type": "text/plain", "value": "Heya!"}],"from":{"email":"sam.smith@example.com","name":"Sam Smith"},"reply_to":{"email":"sam.smith@example.com","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.

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

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

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.

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.

The SET filter:

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.

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.

The PUSH filter:

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.

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.

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

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.