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 theauthenticate() 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 type="text" placeholder="Product key" id="product-key">
  <input type="submit" class="btn" value="Load features">
</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.

Here are the steps for a single page application:

1. Create the page

Host a static file somewhere on the web. In this example we will use requirements.html as the file name.

You can download an example application.

2. Register the application with Aha!

Log in to Aha! and go to Settings Personal Developer OAuth applications to register the new application. The redirect URL should match the URL where you hosted your application in step 1.

3. 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.