Using the MagicSuite API

Using the MagicSuite API (Application Programming Interface) means you can query MagicSuite programatically, without having to use the MagicSuite / ReportMagic user interface. The main interaction is through a REST ODATA interface so it should be possible to use most ODATA client wrappers. Full instructions for using Postman are given below.

A MagicSuite API specific package is available to download from NuGet https://www.nuget.org/packages/MagicSuite.Api
Examples of how to use this package are available on GitHub https://github.com/panoramicdata/ReportMagic.Api.Example
The endpoint documentation can be found here: https://api.docs.magicsuite.net/swagger
If you have access to the Panoramic Data OneDrive, a set of predefined requests is available on in the Development/ReportMagic folder for import into your interface
For help performing different actions with OData queries, please see the OData documentation: https://www.odata.org/documentation/odata-version-2-0/uri-conventions/

Using Postman to Query the MagicSuite API

Postman is a free utility that allows you to interact with different API's by creating and saving different web calls such as GET and POST. These can be grouped for better organisation. Environments are supported allowing variables to be created that allow the same defined calls to be sent to different endpoints, such as Development, Test and Live etc.

Downloading Postman

To download Postman:

Download the desktop application here: https://www.getpostman.com/downloads/
When installing, click to accept all the default settings.
Check your email and confirm it.
Open Postman and follow the remaining steps in Postman.

Adding a new Collection in Postman

Creating a collection in Postman allows you to group together all web calls (requests) for the MagicSuite API. The collection is the top level of grouping, but you can further group by creating folders and sub-folders. To create a collection:

Click on the orange '+ New' button in the top left of the Postman screen.
On the displayed dialog, click on the 'Collection' item.

Enter the name for the collection, i.e. MagicSuite API
Click on the 'Create' button.

Adding a new Environment in Postman

Creating a new Environment in Postman means you can save values you frequently use, such as the API URL and credentials. In a shared workspace, any global variables you create and update will be available to others.

To create the new environment and set up variables:

Click on the orange '+ New' button in the top left of the Postman screen.
On the displayed dialog, click on the 'Environment' item.
Name the environment.
Add an initial variable in the environment for the URL, using the variable name as shown here so that you can refer back to it later:

For development purposes, you may want to duplicate the environment to create further environments for Test and Production.

Authentication

To interact with the MagicSuite API you must authenticate yourself via one of the following methods:

API Token

An API Token can be generated for your own ReportMagic user account. To get one of these:

Go to this URL: https://docs.magicsuite.net/apitokens and click Add.
Copy the Name and the automatically-generated Key, as you will not be able to retrieve these again.
Click Create to create the token.

Return to Postman and add both the token Name and Key to the environment as variables. To access the environment settings, first click on the button showing a Gear / Cog on the top right hand side of the screen:

Then click on the ReportMagic item to show the environment variables:

Next we need to set the authentication method for the collection. By setting it on the collection all child requests can inherit these settings, therefore requiring us to only enter this once.

To edit the collection either right-click on the collection name (listed on the left hand side) or hover over the collection and then click on the button with the three dots. In both cases select the Edit option presented.
In the displayed dialog click on the 'Authorization' tab.
Change the Type to be 'Bearer Token'
Update the Token value to one of the following:
- v1 {{token_name}}/{{token_key}}
- v2 token:{{token_name}}/{{token_key}}

Username/Password

You can use a Base64 encoded form of your username and password for authentication. To do this follow these steps:

Open https://www.base64encode.org/ in a web browser.
Enter your username followed by a colon followed by your password (all with no spaces):

Click the button to produce the Base64 encoded value:
Return to Postman and add these encoded value to the environment as a variable:

Next we need to set the authentication method for the collection. By setting it on the collection all child requests can inherit these settings, therefore requiring us to only enter this once.

To edit the collection either right-click on the collection name (listed on the left hand side) or hover over the collection and then click on the button with the three dots. In both cases select the Edit option presented.
In the displayed dialog click on the 'Authorization' tab.
Change the Type to be 'Bearer Token'
Update the Token value to the exact following text:
- v2 userpass:{{user_password}}

JWT Token

Unlike the previous two methods of authentication, this one differs in that you need to make an initial request to obtain the token.
Return to Postman and add 'username', 'password' and 'token' variables to the environment. Enter credentials for the first two, but leave the token blank for the moment:

Next we need to set the authentication method for the collection. By setting it on the collection all child requests can inherit these settings, therefore requiring us to only enter this once.

To edit the collection either right-click on the collection name (listed on the left hand side) or hover over the collection and then click on the button with the three dots. In both cases select the Edit option presented.
In the displayed dialog click on the 'Authorization' tab.
Change the Type to be 'Bearer Token'
Update the Token value to the exact following text:
- {{token}}

Next we need to create a request that will go and fetch a new token from the API. Ensure the ReportMagic API collection is highlighted.

Click on the orange '+ New' button in the top left of the Postman screen.
On the displayed dialog, click on the 'Request' item.
On the Request dialog enter a name for the request i.e. 'Get Token' and click the save button.
Change the 'GET' to 'POST'
To the right of the 'POST' enter:
- {{reportmagic_api_url}}/authenticate
Click on the 'Body' tab.
Click on the 'raw' option.
Click on the orange 'Text' at the right and change to 'JSON'
Enter the following text for the body: { "Username": "{{username}}", "Password": "{{password}}" }
Click the blue 'Send' button to send the request for a token.
All being well, you should receive a status 200 OK response as shown:

Copy the accessToken value (ignoring quotes) to the clipboard.
Click on the button in the top right that has the eye icon.
Update the current value for the token variable and paste the token:

Creating a New Request

Now that one of the above authentication methods has been configured, you should be able to make requests for data to the API.
To add a request to fetch all Report Schedules:

Ensure the 'ReportMagic API' collection is highlighted.
Click on the orange '+ New' button in the top left of the Postman screen.
Select 'Request' from the dialog.
On the Request dialog enter a name for the request i.e. 'Get Report Schedules' and click the save button
A new Request is created within your collection. Select the request and set the following parameters:

Select 'GET' request type from the dropdown
Paste the following into the request URL:
reportmagic_api_url/odata/reportschedules

Submit the request by hitting 'Send'
If all is correct you should see the JSON encoded response:

Tip: When creating additional requests, you can simply duplicate an existing one and modify the copy.

Using MagicSuite API Client (with JWT authentication)

Open Visual Studio
Create a new C# Console project that targets .Net Core
Right-click on the project and click "Manage NuGet Packages..."
Find the package "ReportMagic.Api" - install the latest version

Example code

using System;

using System.Threading.Tasks;

using ReportMagic.Api;

using ReportMagic.Api.Shared;

using PanoramicData.ReportMagic.Data;

namespace ApiTest

{

class Program

{

static async Task Main(string[] args)

{

// obtain a JWT bearer token for authentication

var url = "https://api.docs.magicsuite.net/";

var response = await ReportMagicClient.GetJwtAsync(url, "Email", "Password");

// create a new client instance to perform the API calls

var client = new ReportMagicClient(new ReportMagicClientOptions

{

Url = url,

AccessToken = response.AccessToken,

AuthMechanism = AuthMechanism.Jwt

});

// fetch all report schedules

var schedules = await client.GetAllAsync<ReportSchedule>();

// write all schedule names to console

foreach(var schedule in schedules)

Console.WriteLine(schedule.Name);

}

Using the MagicSuite API

Using Postman to Query the MagicSuite API

Downloading Postman

Adding a new Collection in Postman

Adding a new Environment in Postman

Authentication

API Token

Username/Password

JWT Token

Creating a New Request

Using MagicSuite API Client (with JWT authentication)

Search