How to access and use the Symbiant API – This is a standard REST API – You will need to contact us to get authorization for your server (IP) to access your data.
Prerequisites #
- A user account with API enabled Role (If you do not have an API role enabled, please submit a support ticket!)
- An EDN (Extensible Data Notation) Parser (Java, JavaScript, Ruby, Python)
- Transit Encoder/Decoder (Java, JavaScript, Ruby, Python)
Please note the above packages are provided by 3rd party developers, Symbiant is not responsible for, nor can we guarantee their suitability for their intended purpose, the use of 3rd party code is done so entirely at your own risk.
Authentication #
API requests are made against a specific user, this can be any user with a registered account and an API-enabled role.
Please be aware that the API will restrict the information you can send/receive in the same way the client applications does, so it is important to ensure your user has enough privileges to perform the tasks required.
API Access Token #
To authenticate access to the API, a secure token is required. To retrieve this token, login as the API-enabled user and select the three dots from the top-right menu and then select “API Token”.
If you do not see this option, please confirm the user has API privileges.
After selecting “API token” a file will be downloaded containing all the necessary information to access the API, it will resemble the image below.
Making API Requests #
The Symbiant API adheres to most of the REST API standards, requests to get data are made with GET.
Creating data with POST, updating data with PATCH, and deleting with DELETE.
However, it is important to note that the URL resource is also prefixed in the Symbiant API with /read/ when getting data and /write/ when writing data.
GET #
Above is a template example of how to run a GET request.
GET Example #
This would return a Risk Register resource with the reference [id] 108.
Note #
The returned data is Transit encode EDN. In the first step, we provided links to EDN and Transit libraries for a few of the more prominent programming languages. If the language you are using is not there a quick Google search may provide you with a suitable library, otherwise, you will need to implement your own based on the specifications again these can be found with a quick Google search.
All attributes are name-spaced keywords, in EDN these look like :some/attribute, e.g. :risk/reference.
GET Filters #
GET provides a few simple filters to help refine the data that is returned. These filters are shown below.
GET /help/ #
To help you work with the API you can execute an API request to GET /help/
This will return details about the attributes available and the structure of the data, again it will be Transit encoded EDN.
Calling GET with the /help/read/ prefix, with or without an ID will return the GET graph,
Calling with the /help/write/ prefix without an ID will return the POST graph, with an ID the PATCH graph.
As well as the data graphs will include details about attributes, whether they are required, collections, what the primary keys are etc.
To understand what resources are available you can either call GET /help or infer them from the client application.
For example, in the client application, if you look at the URL when accessing Risk Registers, you will see a URL like the above image.
This would translate to an API resource of the below.
POST #
The primary key (first attribute in the data graph) is always required, all other attributes are optional unless specified as required or identified by calling GET /help/write/… , see GET /help/ for more information.
It is important to remember that the data submitted must be in EDN format and encoded with Transit.
PATCH #
As with POST, the request body must be in EDN format and encoded with Transit. The body must always contain the primary key attribute, e.g. :risk/reference, otherwise only include the attributes you want to change.
Do not include attributes you are not changing as this will skew your audit trails.
Removing Values #
To remove [retract] values, supply these to :tx/retract.
DELETE #
CAUTION: Issuing this request will immediately delete the specified resource.
Refreshing API Access Token #
The API :id_token will expire after :expires_in (default is 36,000 seconds).
To avoid having to login again and download a new API token, you can use the :refresh_token to get a new :id_token.
This action must be performed before the current token times out, i.e., within 36,000 seconds of logging in as the API-enabled user.
The format for refreshing the API token is shown above.
This will return a new id_token and refresh_token, please be aware that the format of this response will differ from the format of the original API token, it will also not include the URLs or :client_id so these must be taken from the original API token.