Why use a proxy?

The purpose of the apps proxy is to safely allow your widget to communicate with the outside world. The three main functions of the proxy are:

• Whitelist – The proxy is essentially a whitelist of allowed URLs and HTTP methods that you might use when communicating with an API. These URLs are defined concretely or as regular expressions

• Timeouts – For each URL in the proxy configuration you can configure a timeout in seconds. This is the maximum amount of time the proxy will wait for a response from another server

• Settings Injection – Some APIs require some form of authentication, and this is usually based on a “secret” or “key” that must be configured.

Settings injection

Let’s take a deeper dive into settings injection. As mentioned previously, “backend” settings are secret and must only be used in the “backend” of a widget. So, if your widget needs to authenticate an API request, a backend setting will be “injected” or “replaced” into the API request via the proxy. This means that the setting is never revealed to the user, only the server on which the API resides.

A very simple example of this may be an API key that’s passed along with the query string of a request. Let’s create a widget that can run a Google places search using a Google API key.

First, create a widget with a target of “Ticket” and the following setting:

• Name: api_key, Title: API Key, Type: String, Backend Only and Required

Give the setting a value of an API key that you can generate at Google.

Next, add the API URL to the whitelist under the "Proxy" tab of your widget. We'll use a regular expression to match anything after ".../nearbysearch/" in the URL:

https://maps.googleapis.com/maps/api/place/nearbysearch/.*
 copy

Then, in the "body" under the Code tab of your widget, enter the following:

<script>
  Deskpro.client.getProxyAuth().then(function (params) {
	
		fetch(params.proxyUrl, {
			method: "POST",
			headers: {
				"X-Proxy-Url": "https://maps.googleapis.com/maps/api/place/nearbysearch/json?key=__api_key__&keyword=cruise&location=-33.8670522%2C151.1957362&radius=1500&type=restaurant",
				"X-Proxy-Method": "GET",
				"X-Proxy-Authorization": "Bearer " + params.token,
			}
		}).then(function (response) {
		  
			console.log(response);
			
		});
		
	});
</script>
 copy

Let's break down what's going on in this example. Firstly, we're using the browser's native fetch() function in Javascript to actually make the request. Secondly, in order to use the proxy we need a couple of things:

• Proxy URL - The URL of the proxy is unique to your widget, so we provide it for you

• Proxy Auth Token - As you need to authenticate when using the proxy, we provide a token for you to use for each request

The most important part of this example is the placeholder we use for the API key, take a look at the Google Places endpoint URL and you'll notice this in the query string: "?key=__api_key__".

All backend settings replace double underscure delimited placeholders in the URL, headers and body of the request. For example, the placeholder "__example__" would be replaced with the value of the backend setting with the name "example".

Ok, so the example above is a little long-winded as it shows the process of first obtaining proxy parameters and then invoking the API endpoint. To shorten the amount of code you need to write we've provided a utility that makes using the proxy simpler. Replace the code above in the "body" section of the Code tab with the following:

<script>
  var url = "https://maps.googleapis.com/maps/api/place/nearbysearch/json?key=__api_key__&keyword=cruise&location=-33.8670522%2C151.1957362&radius=1500&type=restaurant";
  
  Deskpro.utils.fetch(url).then(function (response) {
    console.log(response);
  });
</script>
 copy

This code does the same thing, but we hide away the proxy setup so you can use Deskpro.utils.fetch() like you'd use the browser's native fetch() function.