AIMMS PRO REST API

The AIMMS PRO REST API allows users to securely interact with the AIMMS PRO cloud platform via a REST interface. This API is designed following the OpenAPI Specification . The API itself can be downloaded in YAML/JSON format from the link https://[account-name].aimms.cloud/pro-api/v1/. The PRO REST API is only available for the PRO Platform running in the Azure Cloud.

Security

Requests made to the PRO REST API are authenticated/authorized by means of API Keys. Users can generate API Keys from their PRO Portal Account settings page by clicking the Add API Key button:

../_images/api-keys1.jpg

Pressing this button will open a new API Key editor, where the user can fill in details regarding the key they want to create. The user should specify a key name, an expiration date, as well as the Scopes for that key. Scopes are the mechanism by which the user can restrict privileges for a given API key to subsets of the PRO REST API:

  1. The Authentication scope allows CRUD operations on Users/Groups

  2. The PublishAIMMS scope allows operations on AIMMS Versions.

  3. The PublishApp scope allows CRUD operations on AIMMS apps.

../_images/api-keys2.jpg

Pressing the Save button will generate a new API key with the properties selected by the user. The new key is shown to the user in a pop-up window:

../_images/api-keys3.jpg

The key will only be shown in plain text once (for security reasons) - so the user is advised to copy it ans store it securely. This key should be sent in the apikey header for every REST call the user want to make using this key for authentication/authorization.

Example: Using Postman to Publish an App

This is an example on how to use Postman in order to perform CRUD operations an AIMMS applications (.aimmspack) using the PRO RESt API:

  1. Start in the Postman request view:

../_images/RequestView.PNG

2. Based on the API method to be tested, select the GET/PATCH/POST/DELETE/etc command from the drop down menu.

3. The request URL depends on the API spec. In some cases, request parameters are present in the URL. Examples of the URL:

https://[account-name].aimms.cloud/pro-api/v1/applications or https://[account-name].aimms.cloud/pro-api/v1/applications/{projectName}/{projectVersionId}

To know what URL should be used, check the corresponding API spec.

4. Headers: within the scope of CRUD on applications, add an “apikey” header with the api key value. Note that the header name must correspond to what is defined in the api spec. Make sure to tick the checkbox after adding the “apikey” field. The rest of the header fields remain unchanged.

../_images/HeadersView.PNG

5. When updating an application, it is necessary to provide the body (in JSON) format. Do not forget to select the “raw” format.

../_images/PatchView.PNG

Note, that it is important that JSON format is selected.

6. When publishing an application it is necessary to provide two fields: metadata and binaryFile. The field metadata needs to be provided in json format. The binaryFile field is a file upload that requires to point to a specific location. Example: (C:\Users\Vlad\Postman\files). Insert the desired .aimmspack in files directory and point to this directory when uploading a binaryFile. Dont forget to select form-data format. Also note that both metadata and binaryFile names correspond to ones defined in the API spec.

../_images/PostView.PNG

Example: Using Postman to Activate an AIMMS Version

Postman can also be used to activate an AIMMS version via the REST API. The same basic one to four steps should be followed as in the previous example. The last step is to perform the actual activation. This is done by performing a PATCH operation on the https://[account-name].aimms.cloud/pro-api/v1/aimms-versions endpoint using the body described in AimmsVersion.yaml in the API schema:

{
    "activated": true,
    "authorization": [],
    "id": "4.82.9.1-linux64-x86-vc141"
}