External Api

The $fetch module lets you make outbound HTTP requests (GET, POST, PUT, DELETE, PATCH) with URL, headers, body, and optional options (isOauth, maxAttempts).

---

Import / Usage

const { AppnestFunctions } = require('appnest-app-sdk-utils');
const { $fetch } = AppnestFunctions;
// or from path:
// const AppnestFunctions = require('<path-to-sdk>/appnestFunctions');
// const { $fetch } = AppnestFunctions;

---

API

request

Method	Signature	Description
request	$fetch.request({ url, method, headers, body, options })	Execute an HTTP request.

Parameters:

Parameter	Type	Required	Default	Constraints
url	string	yes	—	Must start with https:// or http://, max 2048 chars
method	string	yes	—	One of: GET, POST, PUT, DELETE, PATCH
headers	object	no	{}	String key/value pairs; max 1000 keys; each value string, max 1000 chars
body	object	no	{}	String key/value pairs; max 1000 keys; each value string, max 1000 chars
options	object	no	{}	See options below

options (merged into the platform request payload):

Field	Type	Default	Description
isOauth	boolean	false	Whether to use OAuth for the outbound request.
maxAttempts	number	0	Maximum retry attempts (platform-defined behavior).

The SDK builds the outbound options object as: isOauth, maxAttempts, your headers, and userOauthId (empty string unless set by the platform).

Return: Promise<{ headers: Object, body: any, status: number }> — response headers, response body, and HTTP status code.

---

Installation parameters for API calls

Rule — required for all API calls: Any value that comes from app configuration (installation parameters) and is used in a $fetch request must be expressed using the replace syntax <%=installation_parameters.<param_key>%> in url, headers, or body. Do not hardcode these values or read them at runtime; the AppNest framework replaces the placeholders at request time.

When making an API call through $fetch, if the developer needs to use an iparam-specific key/value from their manifest, they must define it under installation_parameters in the manifest.

Defining installation_parameters in the manifest

"installation_parameters": {
  "surveysparrow_api_key": {
    "display_name": "SurveySparrow API Key",
    "description": "Please enter your SurveySparrow API key. You can find it in Settings → Apps & Integrations → Custom Apps.",
    "required": true,
    "secure": true,
    "type": "api_key"
  },
  "surveysparrow_api_url": {
    "display_name": "SurveySparrow API URL",
    "description": "Please enter your SurveySparrow API URL.",
    "required": true,
    "secure": true,
    "type": "string"
  }
}

Using installation_parameters in the request

Reference installation_parameters in the request url, headers, or body using the replace syntax:

• In the URL:
  <%=installation_parameters.surveysparrow_api_url%>/items

• In headers or body:
  <%=installation_parameters.surveysparrow_api_key%>

The same replacement syntax (<%=installation_parameters.<param_key>%>) can be used wherever dynamic values from installation_parameters are required in the request configuration.

For AI / code generation

When generating code that uses $fetch.request:

• options is optional: { isOauth?: boolean, maxAttempts?: number } (defaults: false, 0). Include when OAuth or retries are required per product docs.
• Always use <%=installation_parameters.<param_key>%> for any value that comes from installation params (API keys, base URLs, tenant IDs, etc.) in url, headers, or body. Never substitute a variable or literal for an iparam value in the request config.
• Never hardcode API keys, base URLs, or other config that is (or could be) defined in the app manifest; use the replace syntax so the framework can inject the correct value per installation.
• If the manifest defines an iparam (e.g. api_key, api_url), every $fetch usage that needs that value must reference it as <%=installation_parameters.<param_key>%> in the request object.

Using access_token in headers

To send the platform’s access_token in the request (e.g. for OAuth or API auth), use the replace syntax in headers. The AppNest framework will replace <%=user_oauth.access_token%> with the actual token at runtime.

Example:

headers: {
  Authorization: "Bearer <%=user_oauth.access_token%>",
  "Content-Type": "application/json"
}

Use this in your $fetch.request call; the framework replaces <%=user_oauth.access_token%> before the request is sent.

---

Examples

GET:

const result = await $fetch.request({
  url: 'https://api.example.com/v1/items',
  method: 'GET',
  headers: { Authorization: 'Bearer <token>' },
  body: {}
});

POST with body:

const result = await $fetch.request({
  url: 'https://api.example.com/v1/items',
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: { name: 'Item A', category: 'tools' }
});

With options (isOauth, maxAttempts):

const result = await $fetch.request({
  url: 'https://api.example.com/v1/me',
  method: 'GET',
  headers: { Authorization: 'Bearer <%=user_oauth.access_token%>' },
  body: {},
  options: { isOauth: true, maxAttempts: 3 }
});

PUT / DELETE / PATCH: Use the same shape; set method to PUT, DELETE, or PATCH and provide url, headers, and body (and options if needed).

Using <%=installation_parameters.<key>%> in the request:

// url, headers, or body can use <%=installation_parameters.<key>%> (replaced at runtime)
const result = await $fetch.request({
  url: '<%=installation_parameters.surveysparrow_api_url%>/v1/items',
  method: 'GET',
  headers: { Authorization: 'Bearer <%=installation_parameters.surveysparrow_api_key%>' },
  body: {}
});

Using access_token in headers (framework replacement):

const result = await $fetch.request({
  url: 'https://api.example.com/v1/me',
  method: 'GET',
  headers: {
    Authorization: "Bearer <%=user_oauth.access_token%>",
    "Content-Type": "application/json"
  },
  body: {}
});