API Gateway¶
The API Gateway is the main entry point for the user to access the Quantamatics API. From here, you’ll be able to get Metadata around the API, send API requests using standard HTTP headers and URL or JSON data, and even restart the Gateway environment.
Constructor¶
The API Gateway object has only a few key fields that are populated upon the creation of the API Gateway object. Most importantly, a Session object will bind to the Gateway. Under the hood, this session object will handle any requests to the API and thus must be initialized.
There’s additionally an apiDirectory value which will be set to None upon initializing. The apiDirectory value is a value containing essentially every feature of the Quantamatics API.
Parameters¶
No parameters are available for the API Gateway constructor
Methods¶
getAPIList()¶
This method will allow the retrieval of every method available using the Quantamatics API. These are essentially all the tools available for working with Panels, KPIs, Forecasting etc.
This method will make a GET request via the session object and convert the JSON to a Python dictionary which will be used to set the apiDirectory value. This dictionary will then be converted to a Pandas DataFrame and returned.
Parameters¶
No Parameters are available for the getAPIList() method
Return Values¶
Returns A Pandas DataFrame containing every method available as part of the Quantamatics API.
Exceptions¶
A QException is raised if the session’s token has either expired or has not been set.
If the token has expired, the message “Session Token Not Set” will be returned as part of the exception
If the Access Token is not set, the message will additionally prompt for the
login()method to be used for setting the Access Token
getAPIMetaData()¶
This method provides Metadata on any particular method of the Quantamatics API. If the apiDirectory is not initialized to a non None value, this method will call the getAPIList() method.
This method should be used to understand the necessary parameters, descriptions, and other such information of the methods available within the API list.
Parameters¶
gatewayAPIName
A String value specifying which API method Metadata is requested for. This parameter can be chosen among the values returned by getAPIList()
Return Values¶
Returns A list of dictionaries outlining the properties of the specified method. The following is the full Metadata for a call to gateway.getAPIMetaData("Get FQ Forecast").
[{
'id': 6,
'name': 'Get FQ Forecast',
'assetId': 33,
'assetName': 'Facteus methods',
'description': 'Get fiscal period forecast.',
'params':
[{'id': 149,
'name': 'ForecastMethod',
'type': 0,
'description': 'Forecast Method',
'required': False,
'functionId': 6,
'sortValue': 0,
'context': None},
{'id': 150,
'name': 'ForecastQuarter',
'type': 0,
'description': 'Forecast Quarter',
'required': False,
'functionId': 6,
'sortValue': 0,
'context': None},
{'id': 151,
'name': 'KPIName',
'type': 0,
'description': 'KPI Name',
'required': True,
'functionId': 6,
'sortValue': 0,
'context': None},
{'id': 152,
'name': 'Measure',
'type': 0,
'description': 'Measure',
'required': False,
'functionId': 6,
'sortValue': 0,
'context': None},
{'id': 153,
'name': 'PanelName',
'type': 8,
'description': 'Panel Name',
'required': True,
'functionId': 6,
'sortValue': 0,
'context': None},
{'id': 154,
'name': 'ReturnMeasure',
'type': 0,
'description': 'Return Measure',
'required': False,
'functionId': 6,
'sortValue': 0,
'context': None},
{'id': 155,
'name': 'Symbol',
'type': 6,
'description': 'Symbol',
'required': True,
'functionId': 6,
'sortValue': 0,
'context': None},
{'id': 156,
'name': 'UnitOfMeasure',
'type': 0,
'description': 'Unit Of Measure',
'required': True,
'functionId': 6,
'sortValue': 0,
'context': None}],
'sortValue': None,
'groupId': None,
'groupName': None,
'context': None
}]
Note that the list includes all the Metadata for the specified method in a series of dictionaries, but there is only one dictionary. Within this, the params key has by far the most data, containing its own list of dictionaries describing each parameter. A common operation with this returned data is getting the params necessary. This can be done with the following:
methodMetaData = apiClient.getAPIMetaData("Get FQ Forecast")
methodParams = methodMetaData[0]["params"]
Exceptions¶
A QException is raised if the session’s token has either expired or has not been set.
If the token has expired, the message “Session Token Not Set” will be returned as part of the exception.
If the Access Token is not set, the message will additionally prompt for the
login()method to be used for setting the Access Token
restartGatewayEnv()¶
This method can be used to reset the Gateway environment by sending the appropriate request to the Quantamatics API. This method can be used as a means of debugging and troubleshooting API methods called through a Gateway object.
Parameters¶
No parameters are available for the restartGatewayEnv() method
Return Values¶
If the Gateway object was successfully reset, a True value will be returned
Exceptions¶
A QExeption will be raised if the request made to the Quantamatics API, for the purposes of Gateway restart, has any errors. In this case, a
Falsevalue will be returned.
executeAPICall()¶
The executeAPICall() method is the central component of the Gateway Class and to using the Quantamatics API. From here, you’ll be able to execute any method available in the Quantamatics API, which can be seen through the getAPIList() method.
These methods include the ability to retrieve all panels, key performance indicators, forecasts and more. The information for the appropriate parameters for any method can be found through the getAPIMetaData() method.
This method will call the handleRequest() method of the gateway’s Session object, setting the relative path to api/function/runFunction and setting parameters as appropriate.
Parameters¶
gatewayAPIName
A String value. This parameter dictates exactly which method you intend to execute. Essentially, the name of the method. These names can be found using the getAPIList() method. It should also be noted that this value must match the name of the Quantamatics method exactly.
Therefore, this value must match in terms of all spacing, and case.
params
A dictionary value. This passes all the parameters necessary for the Quantamatics method you wish to execute. These params will be passed to the session’s handleRequest() method internally.
The necessary params can be found using the getAPIMetaData() method. The requested method must also be accompanied by all of its necessary parameters.
Whether a parameter is necessary can be found within the params list within a method’s Metadata. Within the params list will be a series of dictionaries, each having a required key whose value may either be True or False.
Return Values¶
The executeAPICall() method will return a pandas DataFrame containing the appropriate data of the Quantamatics method.
Exceptions¶
A QException will be raised if the response data contains any sort of error. An exception may also be raised if the aforementioned parameters are incongruous. That is, if the String value given for gatewayAPIName is not an available method or if the requested method is not given its required parameters, an exception will be raised.