Getting Started: API Access Keys
Accessing the Nominal API requires an access token. Tokens are provided alongside a valid API license, which is tied to a user account through the Nominal Systems website. A free trial can be created via the website for testing out the API using the Python client or another web-API application. If the account has an activated trial or paid account for the API, the user’s access token is available on the dashboard on the website.
Note
To enquire about purchasing an access token, please contact Nominal Systems at support@nominalsys.com or visit the website for more information.
Adding the API Key
Once the example scripts have been downloaded, the credential_helper.py
script should be edited to include the access token for the API. This is done by adding the token to the GLOBAL_KEY
parameter in the module. By default, the value is left blank. Make sure to save the script as this key will not change between users or sessions.
The fetch_credentials
function will construct a valid set of Nominal Credentials that will enable a connection to the API, provided that the access key is correct. If the key is invalid or mistyped, then no connection to the API will be made. The credentials are passed between all simulation objects behind the scenes to ensure that all objects instantiated are connected to the API.
Setting up the Credentials
In a Python script, to set up the credentials once the key has been added to the GLOBAL_KEY
flag, the following lines of code can be added. This ensures that the helper script provided with the example repository is calling the credentials with the user key.
import credential_helper
from nominalpy import Simulation
# Fetch the credentials
credentials = credential_helper.fetch_credentials()
# Create a new simulation with the credentials
simulation = Simulation.get(credentials)
Using the credential_helper.py
script is not a requirement. Instead, the credential object can be created inside the script and the access token and URL end-point can be directly provided there instead. It simply makes it easier to run multiple scripts without having to change the key each time.
from nominalpy import Simulation, Credentials
# Create the credentials
credentials = Credentials("MY_API_KEY")
# Create a new simulation with the credentials
simulation = Simulation.get(credentials)
Sessions
When a credential object is created, the API will attempt to create a new API session in the cloud. An API session will spin up a dedicated instance to the API that is only accessible by the user who creates it. A standard user will only have access to one concurrent session and new sessions will not know about previous sessions or simulation data. Sessions currently last for 2 hours and any number of simulation calls can be made during that time. Any data outside of the session will be lost and a new session will be created if an API call is made outside of the duration time.
Warning
Any data made in previous simulations will be lost if the session time is over. The current time for a session is around 2 hours from the moment it is created.
When a credential helper creates the credentials, information about the session will be logged to the screen. The session can take up to two minutes to be created when the first API call is made. Provided the user is still in their session, there is no start-up time for a new session.
Note
During the 1-2 minute start-up when a session is first created for the 2-hour window, messages may not appear on the screen and the Python console may appear to be frozen. For debugging options, see the next document on how to enable the various debugging modes to see the status of the startup. Closing the application and starting again will not restart a session and will continue the progress of starting up in the background as it is running on the cloud.
Multiple Sessions
Certain paid accounts will have access to multiple sessions. Within each session, a single simulation can be created. This can enable multiple containers for a dispersed simulation. To create or access a second (or more) session, the same credentials can be passed into the simulation with an index. If the session does not exist, it will attempt to create a session at that index and return a simulation object.
# Construct the credentials
credentials = fetch_credentials()
# Create the simulation handles
simulation_0 = Simulation.get(credentials, index=0)
simulation_1 = Simulation.get(credentials, index=1)
Warning
Sessions are not able to communicate with each other. For multi-session simulations, a unique simulation object is required per session. If the user accounts do not allow for more than one concurrent session (default and trial accounts do not), then an error will be thrown.