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.


Take a look at the simple request app for a demonstration of this feature.

Configure

In order to use the request API, the list of domains should be specified in the manifest.yml file. Please make note of the following restrictions:

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

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

Copied Copy
1
2
whitelisted-domains: - https://example.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 Freshdesk account all have a unique Freshdesk domain. Hence, if your app makes calls to the Freshdesk domain, part of the domain value will come from an Installation Parameter (iparams).
To whitelist such domains, include the following in the manifest.yml file:

Copied Copy
1
2
whitelisted-domains: - https://<%= iparam.subdomain %>.freshdesk.com

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

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
this.$request.get("URL", options) .done(function(data) { // handle data // data is a json string with status, headers and response }) .fail(function(err) { // 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.freshdesk.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
var headers = {"Authorization": "Basic <%= iparam.name %>"}; var options = { headers: headers }; var url = "https://sample.freshdesk.com/contacts/5.json"; this.$request.get(url, options) .done(function(data){ console.log(data); }) .fail(function(err){ console.log(err); });

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 due to an error from the platform, 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": "Error in establishing the connection.", "errorSource": "PLATFORM" }

On request failure due to an error from the App, the err will be returned in the following format:

Copied Copy
1
2
3
4
5
6
7
8
9
{ "status" : 400, "headers": { "Content-Type": "application/json;charset=utf-8" }, "response": "This domain has not been whitelisted.", "errorSource": "APP" }

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

3. POST request with authentication Copied Copy
1
2
3
4
5
6
7
8
9
10
var headers = {"Authorization": "Basic <%= iparam.name %>"}; var options = { headers: headers, body: "Hello world"}; var url = "https://sample.freshdesk.com/tickets.json"; this.$request.post(url, options) .done(function(data){ console.log(data); }) .fail(function(err){ console.log(err); });

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: $ frsh 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
{ "status": 401, "headers": { "Content-Type": "text/plain" }, "response": "Session expired or invalid", "errorSource": "APP/PLATFORM" }

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@freshdesk.com".
502 This status code is returned when there is a network error. If you see this status repeatedly, please contact us at "support@freshdesk.com".
503 This status code is returned when the service is temporarily unavailable.
504 This status code is returned when there is a timeout error while processing the request.


Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

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