Functions
/
HTTP Functions

HTTP Functions

An HTTP Function can be used to call REST APIs, GraphQL, SOAP APIs, or any other HTTP request. Once you create an HTTP Function, both coders and non-coders can use it to build tools in Internal. Max request size for HTTP Functions is currently 10MB.

Note: You must first create an HTTP data source to create custom HTTP functions.


Getting Started

To create or edit a Function, you’ll need to use the Function Editor. You can access the Function Editor from one of two places:

  1. From a Space: Go into Edit Mode and click on the App Data icon in the left nav.
  2. From Company Settings: Go to Data & Functions, click on the desired HTTP data source, and click on the Functions tab.

Once you open the Function Editor, name your Function and select the HTTP data source for which you want to create a function.

To learn how to create a function to read data, check out the below video tutorial:

To learn how to create a function to write data, check out the below video tutorial:

Configure

Specify your HTTP request in the Configure tab.

Above: Github API to view events filtered by repo using the reserved filter parameter ${filter.repo_name}.

URL Parameters

The URL parameters section accepts Javascript template literals. To define variables, filters, pagination, and/or sorting for your request, use dynamic parameters and reserved parameters. Note that you can also choose to provide URL parameters within the path or in the URL Parameters section. Any parameters provided within the URL Parameters section will override parameters provided in the path, if there are conflicts.   

Headers

The header section accepts Javascript template literals. To define variables, use dynamic parameters. Note that any headers you added when you connected the HTTP Data Source will be passed along in addition to the headers you define in this section. If there are conflicting values for the same key, the value defined for the Function will win over the value defined at the data source level. 

Body

This is the content (payload) to be sent through the HTTP request. The body accepts Javascript.

  • None: Will not send a body with this request (typically used for GET and HEAD)
  • JSON: Enter in your JSON body (must be in proper JSON syntax).
  • GraphQL: Enter in your graphQL query in the first box. In the second box, you can add your query variables, formatted as a JSON object.
  • Plain Text: Enter in plaintext for the body. If left empty, the request will send a body with an empty string. 
  • Binary: Use to transmit raw bytes as the body of your HTTP request. (for files, you can uses parameters to specify file.name, file.type, and file.data)

Similar to the URL Parameters and Headers sections, you can define variables (dynamic parameters) for your Function in the payload in the format of user_email.

Above: Example payload for an email service with user_email, first_name, last_name, active, list_id, subscription_status, and tags defined as dynamic parameters.
Above: GraphQL example. Query variables are defined in JSON format.

Run Function

Once you've configured your response, click the button to "Run Function". This will run your HTTP request and generate the raw and transformed responses.

If your request includes the reserved parameters sortBy or filter, you’ll need to go to the Inputs section to configure your sortBy and filter fields. Once that’s done, specify filter/sortBy values, and run your function.

By default, the Transformed Response returns the data from your request. You may need to transform your response further to get it into the proper format. See the next section “Transform” to learn more.

 

Transform

There are a number of reasons why you may want (or need) to transform your response using a Transformer. For example, you may want to:

  • Transform the response into an array of objects or a single object. Most components in Internal require your Function to return an array of objects or a single object in order to display the results of your HTTP request. 
  • Transform the response to return a specific set of fields. In many cases, your request may return too many objects, objects that are deeply nested, or otherwise in a format that doesn’t work for the tools you want to build. 

Transformers can be written using Javascript expressions. Let’s take a look at a a couple examples below:

Example 1:

Below is the response we’re starting with. It’s a single object with a lot of information being returned. 

To only return the data within “list” as an array of objects, we wrote this simple Transformer:

And here’s the new Transformed Response:

Example 2

Below is the response we’re starting with. It’s an array of objects, but the object is nested. 

 

Here’s the transformer we’ve written to pull out specific fields we want the request to return:

And here’s the new Transformed Response:

Inputs

This section is where you configure the inputs of your Function. Think of inputs as fields in a form component, a primary key input that is used to retrieve a record, or filter or sorting inputs for a table component. There are three types if inputs:

Dynamic Parameters

This section auto-populates when you use dynamic parameters (e.g. ${foo}) in your HTTP request. Learn more about dynamic parameters.

Filters

When you add the reserved filter parameter (e.g. ${filter.foo}) to your HTTP request, you’ll also need to specify the corresponding filterable field (e.g. Foo) as an input to your function. Once specified, the filters are available in components like table, detail, and card list. Learn more about reserved parameters.

Sorting

Once you add a reserved parameter for sorting (e.g. ${sortBy}) in your request, you’ll also need to specify the corresponding sortable field in this section (e.g. Foo). Once specified, the sortable field will be available in components like table and card list. Learn more about reserved parameters.

Outputs

This section is where you configure the outputs of your Function. You can manually add outputs or click the Update button to infer outputs from the last execution of your function.  Think of Outputs as table columns or fields displayed in a detail component.

  • Name: This is the name of the attribute (e.g. column name in a table or field name in a Detail Component).
  • Type: This is where you can specify the field type.
  • Key: This is the combination of attributes that make the row unique. Key(s) are used by additional features like automatic row updates and auto linking.

Permissions

You can configure permissions for HTTP functions in Roles & Permissions within Company Settings. Learn more.