Global Report API

Owned by Chris Chambers, created
Last updated: Mar 10, 2023
5 min read

The Air Maestro Global Reporting module includes an API feature that external data reporting systems, such as Power BI, can use to retrieve report data with web requests. This article explains how to configure the API and the requests.

NOTE: In Air Maestro v.3.6.22353.10648, Avinet removed support for creating global report API’s with the API key included in the URL, and replaced them with a more secure method that places the API key in the request headers. When the API key is in the URL it is not encrypted and it will be saved in web server logs, and anyone with the URL can access the report data without additional authorisation. Placing the API key in the headers means that it is encrypted under transport which significantly improves security. However, for backward compatibility, existing URL query string-based reports were not removed and continue to function as normal. We strongly suggest that report admins replace these API’s with new versions where the API key is included as a request header.

 Enabling the API

  1. The API can be enabled for a report on the “Report Schedule” page of the report wizard. Click the “Add API Key” button to generate an API key and enable the API:

     

  2. New API keys will need the expiry date updated. The default expiration date is the current time in UTC, so the date should be changed to suit the needs of the API key. Click the pencil icon to enter edit mode, and change the date. Once set, click the tick button to save the changes.

 Notes for integrators

Web requests

The definition of a web request is outside the scope of this article, but there are many resources online that explain how to configure and send a web request. A great example is https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview.

When defining the web request for the global report through the API, there are several aspects to consider:

URL

The URL contains the information that the Air Maestro servers require to locate the global report. This can be accessed by clicking the “Copy URL” button on the report schedule page of the report wizard, after an API key has been generated:

This will place the URL on the clipboard, so you can paste it somewhere later on.

Data Format

The Air Maestro global report API supports seven data formats:

  1. CSV (Comma separated values)

  2. Excel (Microsoft Excel, .xls binary format)

  3. PDF (Portable document format)

  4. Word (Microsoft Word, .doc binary format)

  5. JSON (Javascript object notation)

  6. Excel07On (Microsoft Excel, .xlsx XML format)

  7. Word07On (Microsoft Word, .docx XML format)

In most cases, integrators will use an exchange standard such as JSON or CSV. The default is CSV, but to specify a particular format a query string parameter should be appended to the report URL:

https://subdomain.airmaestro.com.au/api/reports/123?format=JSON

The API data format specifier is called a “query string parameter”. The query string begins after a question mark (?) is placed on the URL, and can contain one or more name/value pairs separated by ampersands (&). Don’t forget to add the question mark, or else the web request will fail.

Attachment Mode

By default, the global report API will return the report as an attachment (in technical terms, it will request the report with the content disposition header defined with the value ‘attachment’). In many integration scenarios, this won’t be appropriate (such as when configuring a web-based data source in Power BI) so an additional query string parameter should be appended to the URL:

https://subdomain.airmaestro.com.au/api/reports/123?format=JSON&AsAttachment=False

Filter values

It’s possible to define filters for global reports. When filters have been defined, the values for the filters can be provided to the global report API as query string name/value pairs. The details for the names and value format will be shown in the information box below the API key table on the report schedule tab. For example:

This would be included on the URL as follows:

https://subdomain.airmaestro.com.au/api/reports/123?format=JSON&AsAttachment=False&Param255=2023-02-24

Adding the API key to an Authorization header

The API key is used to authorise access to the report, and should be added to the request headers in a header called “Authorization”.

There are many different ways to send web requests, and therefore many different ways to specify the headers. This example shows how to define the header in Postman (a popular API platform for calling APIs):

Please ensure that you include a Host header in your request. This is required by our web application firewall rules - failure to provide a Host header will lead to your request being blocked.

To access the API key, click the “Copy API Key” button on the report schedule page of the report wizard, after an API key has been generated:

This will place the API Key on the clipboard, so you can paste it somewhere later on.

Rate limiting

Each report is rate limited by default to two requests in five minutes. This rate limit can be adjusted on request - contact help@avinet.com.au to request an adjustment.

 Connecting to the API with Power BI

There are several ways to set up web data sources in Power BI - these steps are just one example, but they should provide enough context to use other methods too.

  1. Select “Get data” then “Web” from the ribbon menu:

     

  2. Setup the advanced tab as follows and click OK:



  3. On the next tab, choose “Anonymous” and click Connect. This should retrieve the data from the report and display it in an editor window.