HTTP (REST, GraphQL, SOAP)
/
HTTP Resources

HTTP Resources

An HTTP Resource can be used to display data in Internal using your REST APIs, GraphQL, or any other HTTP request. If you want to enable writing via API, you'll want to create an HTTP Function instead.

Before You Start

Before you create an HTTP Resource, be sure connect a HTTP data source.

Getting Started

Navigate to Company Settings → Data Sources and click on the desired HTTP data source. In the “Resources” section, click on “Add New” and give your resource a name (this is the name that will be used within Internal to refer to this resource). 

Setting up List View

List View retrieves a list of data. This is useful when you want to display many records using a component such as Table, Card List, or Chart. Click on the "Add List View" button to get started.

Request

Path: Specify the URL for your request by completing the path.

Note: You can choose to provide URL parameters within the path. However, any parameters provided within the URL Parameters inputs will override parameters provided in the path, if there are conflicts.

Method: Select the method for your HTTP request (GET, HEAD, POST, PUT, PATCH, DELETE).

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. (All users with the “Admin” role will be able to see headers, including the value. )

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


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 in List View

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.

Filters
  • filter (json): An object of equality filters for the attributes:
    { “id”: 1, "name": "value" }
Sorting (View tutorial)
  • sort_by (string): The name of the attribute to sort by.
  • sort_ascending (bool): Whether to sort ascending or not.
Pagination (View tutorial)
  • 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). View tutorial.
  • 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: 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 your request (usually to put it into a tabular format that is easier to work with). Internal requires your data to be formatted as an array of objects;

Example: 

  
[
    {"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.

---

Example: 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"}
]
  

 ---

Example: 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"
    }
]
  

Preview

Once you've transformed your response, click the button to "Preview and Update Attributes". 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.

Note: If you see an error that attributes weren't found because the transformed response must be an array of objects, go back to the Transformer section to modify the transformer to return an array.

Attributes

If the data returned looks good, proceed to the Attributes tab to view and adjust the fields (columns) for your new resource. "Update Attributes" button at the top allows you to re-sync the attributes with any recent changes - if you just hit "Preview", you won't need to do this.

Underneath, you'll see a list of attributes where 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: 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, you can save this resource now by hitting the "Save" button at the top. You'll be able to use this resource in a Space for components like card lists or tables. If you want to set up this resource for use in a detail component, go to the Detail View tab.

Setting up Detail View

Detail View retrieves a single record. This is useful when you want to display details of a record using the Detail component. Click the purple "Add Detail View" button to get started.

Just like the List View setup, you'll see an area where you can fill out the details of your HTTP request. For the Detail View, there is one key difference: your request is returning a single data record, so you'll need a way to specify the attribute(s) that uniquely identify that record (like the primary key).

You can use dynamic parameters within your request to handle any variables you need (such as the primary key for the record). Simply enter in a Javascript expression with your attribute name This name should match with the attribute names in your data response.

Example:Your API might be set up to receive a customer ID ("12345") within the path v1/customers/, so that sending a request to v1/customers/12345 returns the data record for customer id 12345. You can add the expression ${id} into the path like v1/customers/${id} - this will create the dynamic parameter "id". Later on you can specify how the value for this parameter is populated.

Using Transformers

You can use transformers in the Detail View to modify the result as well - just note that you are returning a single object for the detail view.

Preview

On the preview section, you'll see input boxes for you to fill in any values for dynamic parameters you created while setting up your request.

Note:If you get an error saying that you included a parameter that is not an attribute in your response, make sure the name of your parameter matches up with the attribute name in the response. Ie, if the attribute name is "id", in the response, your dynamic parameter must also be ${id} and not ${customerid} or ${userid}.

Attributes

In the list of attributes, you'll see a new column for Primary Key. We automatically set any parameters used in the detail view as the primary key.

Once you're done adjusting your attributes, you can save this resource now by hitting the "Save" button at the top. With the Detail View set up, you'll now be able to use this resource in a Space for components the detail view.

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.