Avantalytics External API Documentation v1.24

Last Change: June 29, 2013



API Overview

Benefits Of Our External REST API


  • - 100% Secure HTTP Protocol Communication (SSL)

  • - Compact Response Format (JSON)

  • - Speed - 100msec Targeted Avg. Response Time*





Avantalytics provides customers who purchase services access to certain API methods for the purposes of better integrating the data with the customer's in-house and/or third party systems. This documentation describes the available API calls and necessary parameters and return values. Currently all API output is only available via JSON format as described below. See below for details.


Base URL Access


All access to the external API can be reached only through the following address: https://www.avantalytics.com/REST/. For all URLs listed below it is assumed that they are relative to this address. Please note, it is case sensitive.


Customer Specific Security Access Tokens


All API calls below require you to use your unique customer access token in order to receive meaningful responses. This should have been given to you, by us, during the initial API access discussions or during account signup. If you do not have one yet, please contact Avantalytics support (support@avantalytics.com) to discuss the options.

In addition, all API calls require your account ID as part of the request. These two keys together, if they match will provide access to the API calls to which you've been granted access, depending on your account settings.


API Standard Responses


All API calls to registered API URLs will always respond with an HTTP response code 200. Because access is managed within the application layer, the response body itself will determine whether the call actually succeeded or not. The only exception to this rule is a 404 HTTP response code, which will be returned if you provide a mal-formed REST request.

Every API call will provide the following fields providing some information detailing whether the result was successful and/or limited based upon permissions.

The output fragment below shows the response portion relating to a succesful API call. Please note: an API call is considered sucessful from a REST status - even if the data it returns signifies an error occured. In this way, we treat the success of the application call separately from the success of the HTTP response. So, the code below is a successful REST API call, even if the error field value below was "true". It is your job to use the results of these standard fields to determine whether your application should continue it's processing.


{
  "success": true, 
  "error": false,
  "html": "The operation was successful.",
  "msg": "The operation was successful.",
  "permission": true,
  "authenticated": true,
  ...
  msec: 49
}



NEW 7-21-2013: We now provide an additional field in responses shown above 'msec' which is the number of milliseconds execution time per point returned

We recommend checking each of these in your application handling logic before relying on the output that follows. Also note - it is possible for success and error to have different boolean codes. The permission field returns true if your account has been granted access to this API call or the underlying functions supporting it. The authenticated field, by contrast, only tells you whether you have authenticated correctly - a false value here will indicate in incorrect apikey/accountid combination. If this happens, the API will throttle itself to one request every 3 seconds until a correct combination has been submitted. It does this to avert DDoS attacks by potential attackers.


Simple Test GET Request Usage Examples


The examples above are meant to provide you with the minimal request/response for several popular languages. In all cases you should arrive with a json serialized string which you should deserialize into and object or array for consumption.




API Categories