Javascript API


The Aha! API can be accessed directly from Javascript applications without any support from an external server. This makes it possible to create simple, single page, Javascript applications that can display information from an Aha! account in novel ways.

The Javascript API is a wrapper around the REST API and thus supports all of the same capabilities.

Including the API

In the <head> section of your web page include the API Javascript file like:

<script type="text/javascript" charset="utf-8" src="https://secure.aha.io/assets/javascript_api/aha-api.latest.js"></script>

Authentication

Your Javascript application must be registered with Aha!. The registration process will generate the client ID and other information you will need to initialize the API.

Authentication is be performed by the Javascript API when authenticate() is called. The authentication process will popup a new browser window which is used for the Oauth2 authentication and authorization flow. Since the authenticate() code opens a popup window it must be be called from within a user action—like a button click or form submission—otherwise the browser's popup blocker will prevent the user from seeing the authentication page.

Since the API also needs to know the subdomain of the account that should be accessed, we typically use the submission of a form to trigger the authentication process. Here is typical code:

<form id="controls">
  <input type="text" placeholder="Aha! subdomain" id="subdomain"></input>
  <input type="text" placeholder="Product key" id="product-key"></input>
  <input type="submit" class="btn" value="Load features"></input>
</form>

<script>
  $("#controls").submit(function() {
    new AhaApi({
      accountDomain: $("#subdomain").val(),
      // Replace this with your client ID.
      clientId: "b11bbb264c7432421b6abc05fae6bf93f541979b9fb42bbef684ab036487fd5c", 
      // Replace this with your redirect URL.
      redirectUri: "http://lvh.me:4567/scorecard.html"
    }).authenticate(function(api, success, message) {
      var productKey = $("#product-key").val();
      
      // Hide the controls.
      $("#controls").remove();

      api.get("/products/" + productKey + "/features", {}, function(response) {
        // Do something with the features.
      });
    });
    return false;
  });
</script>

In this example the form is also collecting the key for a product which will be used to filter the features that are returned.

Hosting a single page application

Since no server is required for single page Javascript applications they are very easy to host. For example they can be hosted as Github pages, or as files in a Dropbox shared file or folder.

Here are the steps for using Dropbox to host a single page application:

1. Create the page

Create a file within your Dropbox folder (it doesn't matter where) and name it something that ends in .html. In this example we will use requirements.html.

You can download an example application.

2. Create a public link for the page

Right click on the file, and choose "Share Dropbox Link".

Create_dropbox_link

You will get a link in your clipboard that is something like this:

https://www.dropbox.com/s/s2yt3x3olkz152j/requirements.html

If you visit this link you will be invited to download the file. You need to change the www.dropbox part of the URL to dl.dropboxusercontent to tell Dropbox to serve the contents of the link inline:

https://dl.dropboxusercontent.com/s/s2yt3x3olkz152j/requirements.html

3. Register the application with Aha!

Log in to Aha! and go to /oauth/applications to register the new application. The redirect URL should be the URL that you got from step 2 above.

4. Update the application

Update the application file with the client ID and redirect URL for the registered application.

You should now be able to reload the application URL, enter your Aha! subdomain, and the key for one of your products. The key is the uppercase prefix that your features have, e.g. 'APP'. When click the "Load features" button you will be asked to login to Aha! (if you aren't already) and then asked if you want to authorize the application to access your account. After a couple of seconds you should see a list of the features in that product, along with their requirements.

You can now share your application with others - even if they belong to different Aha! accounts. A person who knows the link to your application does not automatically get access to the data in your Aha! account. They still need to login to Aha! using their own credentials and will only be able to fetch data that they already have access to through the Aha! web interface.

Overview

API Resources