Use request method to place secure HTTP calls

Request method is a secure mechanism to send HTTP requests from an app to a third-party or Freshworks domain, without exposing any sensitive information that is part of the request. Through browsers, app users may intercept sensitive information such as API keys or user credentials. Request method safeguards against such exposure. Typically, HTTP requests are routed through proxy servers. In such cases, sending the HTTP requests through the request method helps identify the origin in scenarios where the third-party domain has enabled Cross Origin Resource Sharing (CORS) support.

To use the request method,

1. As part of the app configuration, configure request templates.
2. In manifest.json, declare the template(s) that the app code uses.
3. From the app logic, invoke the configured template(s), and make HTTP requests.

At times, API/resource providers do not want apps to connect to their APIs/resources, unless the app is trying to connect from a known and approved system/org. To get the origin (from where the requests originate) approved, the app devs will have to provide the list of IPs from which the requests can originate. The resource providers will allow-list these IPs in their system and allow any request that comes from these IPs to access their resources. If you want to access such a resource, you will have to provide the following IPs to the resource providers, for allow-listing.

For custom app devsIf you are building an app and if IP whitelisting is enabled for the parent application (the Freshworks' product on which the app is deployed after installation) account, allow-list the following IPs to enable your app to access the parent application resources.

Request templates are snapshots of all the HTTP requests that an app is expected to make.

1. From the app’s root directory, navigate to the config folder and create a requests.json file (if requests.json does not exist).
2. In requests.json, use the following syntax to configure all request templates that the app is expected to use, as JSON objects.

Template substitutions enable the usage of variables in the <requestTemplateName>.schema attributes. During runtime, depending on where the variables are used, they can be populated by:

• Installation parameter (iparam) values
• Contextual data
• currentHost - endpoint_urls
• Stored access tokens
• App settings

Variables can be used only in the following <requestTemplateName>.schema attributes. Also, the type of data that can populate the variables varies depending on the attribute in which the variables are used.

Use the following syntax to declare a template variable that is populated with iparam values at runtime.

<%= iparam.validIparamName %>

variableName must match the context variable name used in the runtime API when invoking the request template. If there is a mismatch in the names, the runtime API call fails.

encode() This function enables encoding secure iparams that are passed as part of the request.

Use the following syntax to declare a template variable that is populated with contextual data, passed through the runtime API that invokes the request template.

<%= context.variableName %>

Important:To construct a dynamic host value that is populated during runtime, though it is possible to retrieve the endpoint_urls through the currentHost data method or from the serverless payload attributes and pass it as contextual data, you should use the currentHost - enpoint_urls template substitution method. For more information on currentHost and endpoint_urls, see Global app concepts.

Use the following syntax to declare a template variable that is populated, at runtime, with the appropriate url of the account (product) on which the app is deployed.

<%= current_host.endpoint_urls.<product_name> %>

Note:During local testing, you can navigate to the System settings page and enter the account URLs that are necessary to test your app.

Use the following syntax to declare a template variable that is populated with an access token value.

<%= access_token %>

Note:This variable is used only in <requestTemplateName>.schema.headers.<header_value> to facilitate the app to place an OAuth request call. This variable should be used when <requestTemplateName>.options.oauth is set to the name of the OAuth configuration object defined in the config/oauth_config.json file.

Use the following syntax to declare a template variable that is populated with the app settings values at runtime.

<%= app_settings.{key} %>

Using request templates, you can upload a file to third-party APIs by simply referencing the files stored in the Object Store. You can configure templates to upload files using multipart/form-data or application/octet-stream.

The uploaded file is referenced by its object store reference identifier in the ref attribute. These files can be directly sent to external endpoints using the invokeTemplate() method.

1. Retrieve the file reference identifier of the files uploaded to object storage by listing all files. For more information, see the list all files.

2. Pass the obtained reference identifier in the API request using

   • multipart/form-data
   • application/octet-stream

multipart/form-data

You can upload a single or multiple files (up to 5) simultaneously to the third-party API. Files are transmitted as multipart/form-data. Under the formData, add the reference identifier as the value of the ref attribute inside the files object as follows:

application/octet-stream

Use this mode to upload one file per request to the third-party API. The file is transmitted as application/octet-stream. Add the reference identifier as the value of the ref attribute inside the file object as follows:

From templates configured in the config/requests.json, in manifest.json, declare the ones that the app code uses, for a specific product.

1. From the app’s root directory, navigate to the manifest.json file.
2. Under modules.common, use the sample shown in the right pane and create a requests attribute.

To send an HTTP request to a third-party or Freshworks domain, in the app code, include the invokeTemplate() method. This method serves as a runtime API call. As part of the call, the app can pass a dynamic context and any other data that the template requires.

Navigate to the server.js file and use the syntax in the right pane to include the invokeTemplate() method.

• requestTemplateName string Mandatory
  Identifier of the request template in config/requests.json and the request in manifest.json. The requestTemplateName must be the same in the app code, configuration (config/requests.json), and declaration (manifest.json).

• An object with the following optional attributes:

  • contextobject

    All contextual data that the template requires, specified as key-value pairs of <variableName>:<variableValue>. <variableName> must be the same as that used in config/requests.json to receive contextual data.

  • bodyobject

    Request body.
    
    Response caching: Requests made through the request method are governed by rate limits. To prevent repetitive calls from breaching the rate limits, the request method comes with an opt-in response caching feature, for front-end apps. The cache and ttl options available as part of the invokeTemplate() method, enable browsers to cache the responses that are retrieved from HTTP calls. The responses are cached in the Browser’s local storage. For requests that haven’t changed since the last call, the response is retrieved from the cache. This conserves the app’s rate limits as the number of HTTP requests made are conserved.

    hide child attributes

    • cacheboolean

      This option is valid only for front-end apps and can be used only with client.request.invokeTemplate(). cache specifies whether a successful response to the HTTP request is cached in the browser’s local storage. The cached response persists in the local storage for a time specified by the ttl value. If no ttl is specified, the response is cached for the default ttl value of 60000 milliseconds.
      Possible values: true, false

    • ttlnumber

      This option is valid only for front-end apps, when cache is true, and can be used only with client.request.invokeTemplate(). If cache is true, ttl (time to live) is the duration (specified in milliseconds) for which the response is stored in the cache.
      Default value: 60000

  • optionsobject

    Valid for apps built using platform v3.1 and later.

    Information pertaining to the account name of an OAuth-secured resource. The multi-account support for an OAuth-secured resource lets you authorize a particular account when a specific event occurs. To learn more, see OAuth.

    hide child attributes

    • accountobject

      Name of the account of an OAuth-secured resource.

      Notes:

      • You can either hard-code the account name or add logic to dynamically retrieve it during runtime.
      • If you choose to hard-code the account name, ensure that it matches the account name entered during app installation.
      • If you want to dynamically retrieve the account name, one approach is to configure a drop-down in the app UI, which allows users to select an account from a list. To learn more, refer to the code of the OAuth sample app.

      Sample code

       $request.invokeTemplate('clientOauth', { options: { account: 'onedrive_1' } }).then(
           function (data) {
             console.log("Onedrive oauth call", data.status);
           },
           function (err) {
             console.log(err);
           }
         );
      

{
"status" : 200,
"headers":
  {
    "Content-Length": 20,
    "Content-Type": "application/json;charset=utf-8"
  },
"response": '{ "Name": "Rachel"}'
}

In the local testing of apps that use the Request Method to make HTTP requests, you can specify a value for the request timeout.

To configure the request timeout to a suitable value, use the fdk config command to set the request timeout as follows.

This command adds or updates the request.timeout attribute with the given value in the .fdk/configs.json file of your app.

For information on how to test an app that uses the Request method feature, see Test your App.

The following table describes common request method errors, associated status codes, and their details.