Request Method

Request method helps you securely call third party APIs from widgets. Using this API, you can prevent malicious users from trying to gain access to critical information, such as user credentials and API keys. The Request method calls are routed through proxies, hence it also supports Cross-origin Resource Sharing (CORS). Request method supports GET, POST, DELETE, and HTTP methods. You can also upload files using Request method.

 

Parameters

The argument of this API must be passed as an object containing the following parameters.

ParameterDescription
url *URL of the third-party API.
The domain of the requestURL must be mentioned under the whiteListedDomain key in the plugin-manifest.
Eg. "whiteListedDomain": ["https://www.example.com"].
type *

HTTP methods supported: - GET, POST, DELETE,PUT and PATCH.

Note:If the request involves a patch method, the value of type must be POST and the value of headers must be { header-override : PATCH }.

headers *HTTP headers supported to be passed in the request.
postBody *Represents entity body. This parameter, which must be passed as an object, is required for PATCH, POST, and PUT requests.If you are making a GET call, make the postBody as empty.
dataKey that contains the data to be appended as queryParams to the URL.
connectionLinkNameKey for authenticating the third-party domain. The value of this parameter must be the same as the one passed in the connectionLinkName value in the plugin manifest.
responseTypeKey that specifies the type of data the response must contain. Values allowed are: arraybuffer, blob, document, json, text, ms-stream, and empty string. If responseType is mentioned in the payload, the postBody and fileObj will not be considered.
fileObjKey that helps upload file objects to the third-party domain. The value of this key must be an array of objects containing the key and file parameters.

 

Sample Request

Copiedvar requestObj = {
             url: "https://api.open-meteo.com/v1/forecast",
             headers: {
                 'Content-Type': 'application/json'
             },
             postBody: {},
             type: 'GET',
             data: {
                 "latitude": "28.65",
                 "longitude": "77.23",
                 "hourly": "precipitation,rain",
                 "daily": "weathercode",
                 "timezone": "auto",
                 "forecast_days": "1"
             }
         }
         ZOHODESK.request(requestObj).then(res => {
             // Implement your logic here
            let weatherdata=JSON.parse(res).response;
            console.log(weatherdata);
         }, (error) => {
             // Implement your logic here
             console.log(error);
         })

Sample response

Copied{
  "latitude": 28.625,
  "longitude": 77.25,
  "generationtime_ms": 1.1839866638183594,
  "utc_offset_seconds": 19800,
  "timezone": "Asia/Kolkata",
  "timezone_abbreviation": "IST",
  "elevation": 227.0,
  "hourly_units": {
    "time": "iso8601",
    "precipitation": "mm",
    "rain": "mm"
  },
  "hourly": {
    "time": [
      "2023-06-15T00:00",
      "2023-06-15T01:00",
      "2023-06-15T02:00",
      "2023-06-15T03:00",
      "2023-06-15T04:00",
      "2023-06-15T05:00",
      "2023-06-15T06:00",
      "2023-06-15T07:00",
      "2023-06-15T08:00",
      "2023-06-15T09:00",
      "2023-06-15T10:00",
      "2023-06-15T11:00",
      "2023-06-15T12:00",
      "2023-06-15T13:00",
      "2023-06-15T14:00",
      "2023-06-15T15:00",
      "2023-06-15T16:00",
      "2023-06-15T17:00",
      "2023-06-15T18:00",
      "2023-06-15T19:00",
      "2023-06-15T20:00",
      "2023-06-15T21:00",
      "2023-06-15T22:00",
      "2023-06-15T23:00"
    ],
    "precipitation": [
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.20,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00
    ],
    "rain": [
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00,
      0.00
    ]
  },
  "daily_units": {
    "time": "iso8601",
    "weathercode": "wmo code"
  },
  "daily": {
    "time": [
      "2023-06-15"
    ],
    "weathercode": [
      3
    ]
  }
}

 


Calling authenticated APIs using Request Method

We can use connections for calling authenticated APIs using Request method. These connections help to fetch data from the third-party service, by including the connectionLinkName key in the Request Method. The authorisation is automatically handled by ZOHO if the connectionLinkName is given.

 

Sample Request

CopiedZOHODESK.get("portal.id").then((orgResponse)=>{
    let orgID = orgResponse["portal.id"];
    
    var requestObj = {
        url: "https://desk.zoho.com/api/v1/tickets",
        headers: {
            'Content-Type': 'application/json',
        },
        postBody: {},
        type: 'GET',
        data: { 'orgId': orgID },
        connectionLinkName: "deskconnection"
     }
     ZOHODESK.request(requestObj).then(res => {
        // Implement your logic here
        console.log(res);
     }, (error) => {
        // Implement your logic here
        console.log(error);
     })
})



Uploading files using Request Method

Request Methods support the file upload. For uploading a file you need to specify the file in the FileObj whose value must be an array of objects containing the key and file parameters.


Note:

Change the content-type in the headers param based on the type of file you upload.

  • Use "multipart/form-data" type for multi part files
  • Use "application/octet-stream" if the file is a byte-stream.

Sample Request

Copieddocument.getElementById("uploadButton").addEventListener("click", () => {
	let fileContent = document.getElementById("fileInput").files[0];
	console.log(fileContent);
	let sampleRequestObj = {
		url: "https://webhook.site/02dca682-3ad2-4bfc-9363-dc5cb1110132",
		type: "POST",
		data: {
		},
		postBody: {},
		headers: {
			"Content-Type": "application/json"
		},
		fileObj: [{ "key": "file1", "file": fileContent }]
	}

	ZOHODESK.request(sampleRequestObj).then(res => {
		// Implement your logic here
		console.log(res);
	}, (error) => {
		// Implement your logic here
		console.log(error);
	})
})

 

Using Config params in Request method

You can make use of placeholders in request method to replace config param values that are received as input from users during installation. To make use of config params, you need to include the config param's name inside double curly braces. Placeholders are supported for the url, data, postbody, and headers parameters.

For example: {{youtubeChannelName}}.

 

Sample Request

Copiedlet sampleRequestObj = {
		url: "https://www.example.com/test/{{RequestId}}", //RequestId is a config param
		type: "POST",
		data: {},
	},
	postBody: {
		"layout_id": "{{layoutId}}",
		"title": "asdf"
	}, //layoutId is a config param
	headers: {
		"Content-Type": "application/json",
	},
	connectionLinkName: "exampleConnection",
}
ZOHODESK.request(sampleRequestObj).then(res => {
	// Implement your logic here
	console.log(res);
}, (error) => {
	// Implement your logic here
	console.log(error);
})

 

Calling Function inside Sigma using Request method

Request method also supports placeholders for certain values required for invoking the functions inside sigma. To know how functions are invoked from widget, refer this section.

Placeholders supported by Request method

Placeholder

Description

{{<configParamName>}}

used to replace value of the config param.
Eg: {{youtubeChannelName}}

{{installationId}}

used to replace installationId of the extension
{{enCapApiKey}}used when calling function inside Sigma from Widgets.
{{securityContext}}used for security purposes, for authentication purposes
{{extensionVersion}}helps to replace extensions version.
{{resourcetype.resourcename.id}}used to replace extension resources id.
Eg: {{fields.examplefield.id}}
{{resourcetype.resourcename.apiName}}helps to replace apiName of the extension resource
Eg: {{fields.examplefield.apiName}}
{{sigmaInstallId}}used when calling function inside Sigma from widgets.

 

Limitations

  1. You can make a maximum of 50 requests per minute.
  2. You can upload a maximum of 3 files per minute.

 

    Errors From Request Method

    Request method does some validations before executing the given URL. Hence, Request method throws two kinds of errors, such as errors thrown by the URL called and the errors that are thrown by the Request method. For the errors that are thrown by the Request method, appropriate response code and message will be given in the response of the Request method.Some of the common errors while using request method are given below.

    Error Message

    Reason

    {errMsg: 'No entry found in plugin-manifest whiteListedDomains for requested URL'}If the URL's Domain is not present in the whiteListedDomain of the plugin-manifest.
    ProcessGetRequest : Error => TypeError: e.postBody is undefinedThis error will be shown in console if PostBody is not specified in the Request Object.
    {\"statusMessage\":\"com.zoho.dre.exception.DREException: Invalid connectionName or Id\",\"status\":\"false\"}Connection is not connected or the provided connection in the connectionLinkName is not present.
    {\"statusMessage\":\"Error due to - 'Internal Exception'\",\"status\":\"false\"}Key is not mentioned in FileObj while uploading a file.