How to Make API Calls from a Browser-based Application

When developing an HTML5 application, it's common to have JavaScript executed by the browser do most of the work of UI, updates, interactions, and data retrieval. Browsers, however, enforce a "same-origin policy" about requesting data, denying any requests to APIs from third-party domains. For modern browsers, however, Cross-Origin Resource Sharing (CORS) allows browsers to disregard the restriction. Most of aWhere's APIs support CORS.

Learn more about Using CORS

Because the APIs support CORS, you'll be able to use whatever front-end library you prefer (e.g., JQuery), to make API (or "XHR") requests as described in our documentation. The only catch is that you'll need to be sure to include your Access Token in an Authorization header; the code for various front-end libraries will be different, but here is a JQuery example:

$.ajax({
    type: "GET",
    url: URL,
    headers: {
        "Authorization": "Bearer " + ACCESS_TOKEN
    }
}).done(function (response_payload) {
    //do something with the response body
}).fail(function () {
    //handle the connection error
});

Security Considerations

While CORS support will allow you to make API calls directly from a browser-based application, there are important security considerations to remember.

The APIs leverage OAuth2 tokens for security, and the tokens are generated by passing your API key and secret to the token API. You cannot do this step in the browser, because it risks the exposure of your credentials. JavaScript is inherently insecure code, and even the most minified or obfuscated code can be picked apart to find your credential.

Proxy Design Pattern

Instead of generating a token from the browser, you should have a simple server-side script do the work of generating the token and then passing that token to your browser-side code. Tokens expire after an hour so the risks from a token being exposed are less than if your API credential is compromised. To encourage this design, the Token API does not support CORS.

There are a couple of ways to implement this workflow. We call this the Proxy Design Pattern because your server is acting as a proxy to aWhere's Token API. It essentially sits between your HTML application and aWhere, for the sole purpose of securely generating your API token.

First, you can generate the token when the application is built on the server, before it is downloaded to the browser. You would likely build the token into a JavaScript variable available to the page's code. This is a simple solution, but is best when your user is not expected to stay on one page for more than hour. Otherwise the token will expire and the page will not be able to make API calls to aWhere until it is reloaded. However, this solution also means someone could see the token by viewing the page's source code.

Workflow for First Option

Second, you can build your own lightweight API that the page code uses to retrieve the token. On your server, the script generates a token and delivers it to the JavaScript code, where it is stored in memory as a variable value. Then, if the user does stay on the page more than an hour, the code can simply request a new token from your server without having to reload the whole page. And while a debugging console could be used to find the token from memory, it would be less obvious than the first option.

Workflow for Second Option

Extending the Proxy Pattern

Before CORS became commonplace, the Proxy Pattern was the most efficient way for JavaScript apps to make API requests. You could easily choose to pass all API calls through your server. This would be the most secure because both your keys and your token are protected. However, it is less efficient, places higher burden on your server, and can introduce latency to the API calls.