Getting Started
Datasources
Spaces
Functions
Components
Super Records
Permissions
Settings
Advanced

HTTP Resources

You can create a resource and populate its data through an HTTP request. In order to do this, you must first connect a HTTP data source.

Then, navigate to Company Settings (left navigation) → Data Sources (tab). Click on the desired HTTP data source. 


In the “Resources” section, click on “Add New”. This will bring up a screen where you can configure how we'll read the data from your HTTP data source: 

Enter in a name for your custom resource at the top - this is the name that will be used within Internal. 

On the next line, select the method for your HTTP request (GET, HEAD, POST, PUT, PATCH, DELETE). Specify the URL by completing the path.

  • Note that you can provide URL parameters within the path, if you choose to do so. Any parameters provided within the URL Parameters inputs will override parameters provided in the path, if there are conflicts.

In the tabs for URL Parameters, Headers, and Body, you'll fill out the rest of your HTTP request:

URL Parameters: Add key and value pairs to be passed along within the URL.

Headers: You can add additional key-value pairs to be passed along in the request header to read this data.

- If you also defined key-value pairs when you connected the HTTP data source header, any pairs defined here would be passed along in addition to those defined in the data source. If there are conflicting values for the same key, the value defined for the resource will win (over the value from the data source).

- Note: All users with the “Admin” role will be able to see headers, including the value.


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 JSON object.

- Raw: Enter in plaintext for the body. If left empty, the request will send a body with an empty string.

Using Parameters

Internal provides the following reserved parameters to support filtering, sorting, and pagination for the data in your resource. Depending on how your API is set up, you may need to specify some of these parameters in the HTTP request so that Internal can retrieve the data correctly.

  • filter (json): An object of equality filters for the attributes:
    { “id”: 1, "name": "value" }
  • sort_by (string): The name of the attribute to sort by.
  • sort_ascending (bool): Whether to sort ascending or not.
  • page_number (int): The number of the page to retrieve (same as page_offset / page_size).
  • page_offset (int): The record number to start at (offset).
  • page_size (int): The number of records per page.

Use a JavaScript variable to include the following parameters. In template literal inputs (allowed in path, URL parameters and headers), use the ${variable} syntax, like ${page_size}. In the JSON body field, simply specify variable, like page_number.

Examples

For example, your API may ask for the page number to be passed as a URL parameter called pagenum. In this case, you would fill in pagenum as the Key and ${page_number} as the Value within URL parameters tab.

Or your API may ask for the attribute to be sorted on to be included in the header, called SortAttribute. In this case, you would fill in SortAttribute as the Key and ${sort_by} as the Value within the Headers tab.

Or, your API may return a list of users and filters this list using name (passed as a URL parameter). In this case, you would use name as the Key and ${filter.name} as the Value with URL parameters.

Using Transformers

Transformers let you modify the result that is returned by this request (usually to put it into a tabular format that is easier to work with). The data needs to be formatted as an array of objects; Ex: 

[
    {"id": 1, "city": "San Francisco", "state": "CA"}, 
    {"id": 2, "city": "New York", "state": "NY"}
] 

The identifier data is used for the return value and you can use JavaScript expressions to modify this result.

Ex: If data (returned value) is an object with a nested array of items, you can specify data.items to return the array of objects.

Data:

{    items: [        
				{"id": 1, "city": "San Francisco", "state": "CA"},         
        {"id": 2, "city": "New York", "state": "NY"}    
      ],    
      otherInfo: {}
 }

Transformer:

data.items

 

Transformed response:

[    
	{"id": 1, "city": "San Francisco", "state": "CA"},     
	{"id": 2, "city": "New York", "state": "NY"}
]

 

Ex: If data (returned value) is an array of data with values you want to modify or remove from the result, you can use a transformer. For example, in the below example we want to concatenate first and last names, as well as hide the SSN.

data:

[
    {
        "id": 1,
        "firstName": "Michael",
        "lastName": "Scott",
        "SSN": "123-12-1234"
    },
    {
        "id": 2,
        "firstName": "Pam",
        "lastName": "Beasley",
        "SSN": "789-78-7890"
    }
]

 

Transformer:

data.map(user => ({
    id: user.id,
    fullName: `${user.firstName} ${user.lastName}`
}))

 

Transformed response:

[
    {
        "id": 1,
        "fullName": "Michael Scott"
    },
    {
        "id": 2,
        "fullName": "Pam Beasley"
    }
]


Saving Your Resource

Once you've finished building out your HTTP request, click the purple "Preview" button. This will generate a preview of the data that is returned below - you'll see both the raw response as well as the transformed preview.

You'll also be able to click on the Attributes tab to view the fields (columns) available in your new resource. Here, you can adjust the display name for each field as well as the type of field it is (string, integer, JSON, etc). You can use the checkboxes to the right of each attribute to allow this attribute to be sorted on or filtered on by a user.

Note that in order to sort on a given attribute, the "sortable" checkbox must be checked AND "sort_by" & "sort_ascending" reserved parameters must be specified in your HTTP request. Similarly, in order to filter on a given attribute, the "filterable"checkbox must be checked and the "filter" reserved parameter must also be specified (with that attribute).

Once you're done adjusting display names and field types, click "Save" at the top to save your HTTP Resource. You'll now see it as a resource that you can view and manage within your Data Sources. You should also be able to use this resource in a Space by selecting it as a resource for certain components, like tables or card lists.

 

Things to know about HTTP resources:

  • You can configure permissions for HTTP resources in Roles & Permissions within Company Settings.
  • You can create HTTP functions to edit data within your HTTP resources.
  • You will need to set primary keys manually -- see Managing Data Sources.
  • Only admins can create HTTP resources.