Request API

Request API should be used whenever you are making HTTP requests to third party domains, using this API will avoid exposing sensitive information such as your API key or user credentials. Previously, this information was visible by inspecting the page where the app was running. The other benefit is CORS support as requests will be routed through a proxy.


Note:
1. All apps that make requests to third party domains must use the request API or else they will not be published to the Marketplace.
2. Requests made using the request API should return string, JSON or XML data types.
3. The timeout for request is 6 seconds.
4. There is a rate limit of 50 requests per minute per app per account.


Configure

In order to use the request API, the list of domains should be specified in the manifest.json file.

  • You must use only HTTPS.
  • Do not use IP addresses.

Example 1
If your app makes an API call to "https://example.com/api/1.json", include the following in the manifest.json file:

Copied Copy
1
2
3
"whitelisted-domains": [ "https://www.google.com" ]

Example 2
Sometimes you will have to make calls to a URL whose name is not static. For e.g users who sign up for a Freshservice account all have a unique Freshservice domain. Hence, if your app makes calls to the Freshservice domain, part of the domain value will come from an Installation Parameters (iparams).

To whitelist such domains, include the following in the manifest.json file:

Copied Copy
1
2
3
"whitelisted-domains": [ "https://<%= iparam.subdomain %>.freshservice.com" ]

In the above example, subdomain is the display name of the installation parameter.


Example 3
Wildcards are supported to enable you to whitelist all subdomains of a parent. For e.g an app want to make requests to multiple Freshservice accounts - menswear.freshservice.com, kidstoys.freshservice.com, accesories.freshservice.com etc.

To whitelist such domains, include the following in the manifest.json file:

Copied Copy
1
2
3
"whitelisted-domains": [ "https://*.freshservice.com" ]
Usage

Request API should be defined in the app.js file using the following syntax:

Copied Copy
1
2
3
4
5
6
7
8
9
10
client.request.get("URL", options) .then( function(data) { //handle "data" //"data" is a json string with status, headers, and response. }, function(error) { //handle failure } );

PARAMETER DESCRIPTION
URL The URL is mandatory to make the request API call.
options The options value is a JSON object. This object can include the following properties:
  • headers: HTTP Headers
  • body: Entity body, applicable for PATCH, POST, and PUT requests. Body should be a string.
data The data received from the request API if the request is successful.
err Data received from the request if an error was encountered.

Using iparams

Iparams can be used in the requests as part of the URL, header, or body. The iparams should be enclosed within tags as shown in the example below:

Copied Copy
1
https://sample.freshservice.com/?data=<%= iparam.name %>

There may be other information (apart from API key, username, and password) that is included as part of a request which you may want to hide. For example, imagine you are making a call to a third party resource which requires your passport number as part of the URL. This can be hidden by using the following syntax:

Copied Copy
1
https://passport-office.com/user?id=<%= iparam.passport %>
Sample Requests

Request API should be defined in the app.js file, you can use the following sample requests for reference:


1. GET request with authentication Copied Copy
1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Basic <%= encode(iparam.api_key) %>"}; var options = { headers: headers }; var url = "https://sample.freshservice.com/itil/requesters/5.json"; client.request.get(url, options) .then ( function(data) { console.log(data); }, function(error) { console.log(error); });

On successful request, the data will be returned in the following format:

Copied Copy
1
2
3
4
5
6
7
8
9
{ status : 200, headers: { "Content-Length": 20, "Content-Type": "application/json;charset=utf-8" }, response: `{ "Name": "Rachel"}` }

On request failure, the err will be returned in the following format:

Copied Copy
1
2
3
4
5
6
7
8
{ status : 401, headers: { "Content-Type": "application/json;charset=utf-8" }, response: [{"message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID"}] }

2. GET request without authentication Copied Copy
1
2
3
4
5
6
7
8
9
10
var options = {}; var url = "https://httpbin.org/get?arg1=hello_world"; client.request.get(url, options) .then ( function(data) { console.log(data); }, function(error) { console.log(error); });

3. POST request with authentication Copied Copy
1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Basic <%= encode(iparam.api_key) %>"}; var options = { headers: headers, body: "Hello world"}; var url = "https://sample.freshservice.com/tickets.json"; client.request.post(url, options) .then ( function(data) { console.log(data); }, function(error) { console.log(error); });

OAuth Request

For information on how to make an OAuth request, see Usage in the OAuth section.

Local Testing

Open your console, navigate to your project folder, and execute the following command: $ fdk run

During local testing, you may see a shield icon in the browser address bar. Clicking on the icon will display a warning message.

This warning message is displayed as the support portal runs on HTTPS while the server that is used for local testing runs on HTTP. Please click "Load unsafe scripts" to continue testing.

Errors

In case of failure when making requests, a status code will be displayed along with a message to help troubleshoot the issue.

Below is an example of a status code and message:

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
{ "status": 401, "headers": { "Content-Type": "text/plain" }, "response": [{ "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" }] }

The following table lists all the supported status codes:

STATUS DESCRIPTION
400 This status code is returned due to invalid input. For example, if you are making a request to a domain that has not been whitelisted, you will receive this status.
401 This status code is returned if you have performed an unauthorized request.
429 This status code is returned when the number of requests exceeds the threshold.
500 This status code is returned if the server encountered an unexpected error. If you see this status repeatedly, please contact us at "support@freshservice.com".
502 This status code is returned when there is a network error. If you see this status repeatedly, please contact us at "support@freshservice.com".


Log in with your Freshservice account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.