Getting Started

 API Groups

 MagicINFO REST API 2.0 features a comprehensive collection of functions spanning various parts of functionality available in MagicINFO Server. In order to make the API easier to digest, and come to terms with using these functions, they have been divided into so called API Groups. Each API Group corresponds to a particular part of MagicINFO Server functionality. Below is a rundown of all twelve API Groups present in MagicINFO REST API 2.0, as well as a description detailing their use.

 

 API Access Authentication

 Before you can start using the prowess offered to your within the MagicINFO REST API 2.0, you must first authenticate yourself as a validated user. As such you will need to use the functionality provided within the Authentication API Group.

To view the list of available functions within this API Group, you will need to open up MagicINFO's Swagger UI page. In order to do so copy & paste this URL into the web browser on the machine on which MagicINFO Server 8 is installed, and you are already logged on, or alternatively copy & paste the link below, and input localhost or the public IP number, or domain of your MagicINFO Server 8 installation depending on whether you are using MagicINFO Server in a local network, or over the internet.

MagicINFO Swagger UI page URL syntax: 

http://<<input localhost or your public IP or domain here>>:7001/MagicInfo/swagger-ui.html?urls.primaryName=REST%20API%20v2.0

 For example:

http://192.168.0.10:7001/MagicInfo/swagger-ui.html?urls.primaryName=REST%20API%20v2.0

Once you have the Swagger UI displayed within your web browser you should see a screen similar to the one below:

 If you do not see the screen as above, either ensure you have the correct URL, and are logged into MagicINFO Server, or click on the drop-down menu located to the right of "Select a spec" in the top-right of the page, and select "REST API v.2.0".

From this screen you can now click and expand on each API Group to view the list of available functions. Let's click on the Authentication API Group to learn more about the list of available functions:

In order to authenticate yourself as a valid user and successfully start using the API you will need to send a HTTP POST  request to a function resource named /restapi/v2.0/auth as shown below:

As can be seen this function requires a list of parameters when being called, some which are mandatory, while others optional. In order to receive a token in the response message of this HTTP POST  request, you will need to send a request to the /restapi/v2.0/auth URI, and provide two parameters: "username": "string" & "password": "string" in the BODY of the request. Furthermore, before this function can be successfully executed by MagicINFO Server, you will first need to append the relevant data of your existing environment, as follows:

 API function URI:

http://{input localhost or your public IP or domain here}:7001/MagicInfo/restapi/v2.0/auth

 For example:

http://192.168.0.10:7001/MagicInfo/restapi/v2.0/auth

 Function parameters (to be included in BODY of HTTP request):

"username": "{your login goes here}"

"password": "{your password goes here}"

 For example:

"username": "admin"

"password": "admin1234567890"

 In order to successfully authenticate yourself as a validated user in your MagicINFO Server environment, you must provide the login credentials to your admin account, and ensure the parameters you send are in valid JSON format. If you are a beginner or unsure if the data you are sending in your API function requests is valid JSON, you can use an online JSON data validator such as JSONLint.

Providing a valid HTTP POST  API request has been made as above, MagicINFO Server will respond with a token, which will look similar to the following:

 

 This token must be used for all future MagicINFO REST API 2.0 HTTP requests that you make, and its value must be passed as a parameter named api_key within the HTTP request HEADER. Failure to do so will result in automatic termination of the request by MagicINFO Server. All tokens fed as api_key values have an expiration date due to non-use. This is implemented as a security measure. If you do not make frequent API requests then your token will expire. Should this happen you will need to repeat the above process to acquire a new token, and then once again use it as the value of api_key. If you are writing a complex application involving many uses of the MagicINFO REST API 2.0, then it is recommended that you write additional code, which will dynamically request, or refresh a token before each subsequent, and normal (non authentication related) API request. 

 Debugging Errors

Each time you execute a HTTP request to MagicINFO REST API 2.0 you will observe one of two possible outcomes:

 Your request will complete successfully

 Your request will fail for one or more reasons

If your request completes successfully then it means the data you have passed in either thes URI or BODY of the HTTP requests has been executed. If so MagicINFO Server will respond with a HTTP Response code 200, meaning success.

If your request fails, this can be due to any number of reasons, and a good indication is the HTTP Response code with which MagicINFO Server responds.  Consequently observe the HTTP Response code provided by MagicINFO Server, and debug as follows:

  HTTP Response code 400:

If  MagicINFO Server responds with HTTP Response code 400 then it means the syntax of your request is invalid. Make sure you are calling the MagicINFO REST API 2.0 function URI correctly, and with spelling mistakes, or you are not missing data, especially if calling a GET HTTP Method API function. It is also worth checking if any parameters you are passing the BODY conform to true JSON formatting. If in any doubt, please use an online JSON Validator, such as JSONLint.

  HTTP Response code 401:

If MagicINFO Server responds with HTTP Response code 401 then it means you are trying to access the MagicINFO REST API 2.0 without valid authentication. If you do not yet have a token, which you then need to pass in all requests as a parameter named api_key, of if this token has expired, then either request a new function as detailed above, or refresh your existing token.

 HTTP Response code 403:

If MagicINFO Server responds with HTTP Response code 403 then it means access to the API resource is forbidden. If this happens MagicINFO REST API 2.0 is currently configured to provide a further description, which should help you resolve the issue. In many cases this is also due to trying to access the MagicINFO REST API 2.0 without valid authentication (see above).

 HTTP Response code 404:

If MagicINFO Server responds with HTTP Response code 404 then it means MagicINFO REST API 2.0 cannot recognise the function URI you are calling. Similarly to HTTP Response code 400 above, check to make sure the URI is spelled correctly, and free from any human typos.

 HTTP Response code 500:

If MagicINFO Server responds with HTTP Response code 500 then it means MagicINFO REST API 2.0 could not execute your request, but is unable to state exactly why. This could be a problem with the function URI syntax, the parameter you are passing in this URI, the date format you are passing in the BODY of the request, its data type, or any syntax combination thereof. It is also possible that you are not passing all necessary parameters to complete the API function call.

 Understanding Function Parameters

MagicINFO REST API 2.0 is powerful, but can also be complex. As such, it makes sense to understand the function parameters and values that you are sending in your requests, and why. In order to enhance this motive, it is recommended that you pay regular visits to the Parameter Reference. This can be useful both before making a request - in order to succeed without failure, as well as after - when you need to debug any possible errors.