Accessing Astera’s Server APIs Through a Third-Party Tool

1. Introduction

This article is intended to provide a brief user guide to Astera users on how they can use Astera Server APIs to perform some commonly used actions without using the Astera Client.

The document covers the following operations:

Configure Astera Server properties
Configure Astera Server license
Deploy user projects on Astera Server
Schedule/execute the jobs

2. Environment setup and tools used

For the use cases below, Astera Integration Server is installed on a Virtual Machine and no Astera Client is going to be used to perform operations. However, some images of the Astera Client have been used for description purposes. We will use the Postman client as a third-party tool to send API requests to the Astera Server to perform several tasks.

3. Use Cases

‘POST /api/account/login’

This API returns the bearer token that can be used to make calls to the Astera Server. It also returns some more information about the user.

3.2. Configure Server Properties

3.2.1. Configure Server properties API example (/api/Server/Config)

In this section, we are going to use the API ‘POST /api/Server/Config’ to change Server Profile of the Astera Server.

Here, we can see that a Server Profile named DEFAULT has been selected in our Server Properties.

To change this profile shown in the image above, we must provide the JSON body containing information related to the Repository Database with the name of the desired Server Profile in the POST request.

Note: Server Profile 2 was created in advance to be used in this request.

Once we have provided the relevant information, we can send the request.

We can see that a 200 OK success response is received in the image above.

We can verify using the Astera Client that we have successfully configured our server with the desired profile ServerProfile2.

Note: To see how the JSON request body is structured or what fields are required for a successful POST request, send a request to the GET /api/Server/Config API. This API will return the configured server’s properties in the response.

A sample server config JSON body is provided here for reference.

3.2.2. Server properties configuration API Parameters description

3.3. Manage Server License

3.3.1. Change license key API example (/api/License/Key)

In this section, we are using the POST /api/License/Key API that allows the user to change the server license. We will also use the POST /api/License/Activate API to activate the license.

Go to Server > Configure > Enter License Key. Here, we can see a user ‘Nisha’ of the organization ‘G’ is registered with an active license.

To change the license key and register the user, we must provide the User, Organization, and License Key in the JSON request body. Refer to image below.

Note: The license key was taken in advance for this demo.

Once we have provided the relevant information, we can send the request.

In response, we can see that a 200 OK success status is received indicating that the license key has been changed.

Now, go to Server > Configure > Enter License Key, and notice the license properties. We can see a user Nisha of the organization Astera with a different/new license key has been registered.

3.3.2. Change license API Parameter description

3.3.3. Activate license API Example (/api/License/Activate)

However, the license is not activated yet. To activate the license, we can simply send a request to the /api/License/Activate endpoint. After sending the request, we can see that a 200 OK response is received.

Note: To receive a 200 OK response, we must send an empty text in the body otherwise the request will result in an error. Also, this API only activates the license online.

Go to Server > Configure > Enter License Key again. Here, we can see the status of the license is activated now.

3.3.4. Activate license Parameter description

No parameters required, send an empty body here.

3.4. Configuring Cluster settings

Configuration of cluster settings is important before proceeding with the project deployment.

3.4.1. Cluster settings API parameters description ‘/api/Cluster’

The JSON payload sample for the cluster configuration is attached here.

3.5. Archive File Deployment (User project deployment)

To successfully deploy an archive file (User project .car file) using the APIs, a user must perform the following prerequisites:

Upload the archive file (User project .car file) to the deployment directory.
Upload the config file to the deployment directory. (optional)

3.5.1. Uploading the Archive File/Config File to the Deployment Directory

There are two methods to do this, let's see each in action.

a. Example of using ‘POST /api/UploadFile’

The user can upload the config and .car files to the deployment directory using APIs. There is a possibility that a user might delete or move the config or .car file from their local machine. To avoid any issues, it is recommended to first upload these files to the deployment directory.

To upload the file, use the ‘POST /api/UploadFile’ API. In this API, we must provide two query parameters:

FileTypes: Extension of the target file e.g., cfg for the config file, car for Archive files.
TargetFileName: Here, we define the target file’s name e.g., Testing.

Next, we need to configure Request Body for this API. For the request body, select the form-data content type, select the Key type as File and provide the desired archive file (.car file) in the Value. Click Send.

Note: The archive project file (.car file) was created in advance for this demo.

Here, we can see that a 200 OK response, with a file path of the deployment directory’s archive file, has been received. Please copy down this path on your notepad as we need to use this path while creating the deployment.

Similarly, we can upload the config file to the deployment directory using this api/UploadFile endpoint.

Parameter description of /api/UploadFile

b. Using the ‘POST api/UploadCarFile’

An archive file (.car file) can also be uploaded to the deployment directory via another API i.e., ‘POST api/UploadCarFile’.

In this API, we do not need to specify the query parameters. Simply select the archive file (.car file) in the body and click Send. Here, we receive the archive file path in the response.

The uploaded files can also be seen in the deployment directory.

Parameter description of api/UploadCarFile

3.5.2. Creating the Project Deployment

3.5.2.1. Using POST /api/Deployment example

Now, let’s proceed to the deployment creation. To create a deployment, we must use the ‘POST /api/Deployment’ API.

In this API’s Request’s Body, we must provide info such as:

Relevant archive (.car) and config (optional) file paths (both local and deployment directory file paths)
The deployment’s name, its ID, and its activation state, etc.

After defining the body, we can click Send.

Here, we can see a 200 OK response has been received indicating that a deployment has been created.

Open the client and go to Server > Deployment Settings > Deployment. In the deployment window, we can see the archive file has successfully been deployed.

A sample deployment JSON body is attached here for reference.

Please note the following:

To create a new deployment, we must provide the field “Id” as 0. We should also provide a unique deployment “Name” i.e., not the same name as an already existing deployment. Otherwise, the request will result in a 400 Bad Request error.
If we provide a non-zero “Id” field e.g., Id = 7, the server will consider this request as an update request, and if a deployment with ID 7 already exists on the server it will be modified/updated.

3.5.2.2. Parameter description of /api/Deployment

3.5.3. Post Deployment Modification

The ‘POST /api/Deployment’ API can also be used to modify an existing deployment. In this API’s Request Body, details of an existing deployment are required.

In this scenario, we want to update the name of the above-created DeploymentTesting. However, we do not have its details available.

So, to gather the details, we firstly use the ‘GET api/Deployments’ API to fetch the info of the existing deployment. Then, we copy the deployment Id, UpdateDtTm, and CreatedDtTm fields from the response.

Note: This GET API returns information for all the deployments on the server. Since we desired to modify only one deployment DeploymentTesting, we copied these highlighted fields only.

Now, in the POST Request’s Body, let’s change the deployment Name to DeploymentTesting_Modified and replace the values of Id, UpdateDtTm, and CreatedDtTm fields with the values copied from the GET response.

Let’s send the request.

A 200 OK response is received. Now, go to Server > Deployment Settings > Deployment, in the deployment window, we can see the modified deployment name.

Note: Each time we update an existing deployment the UpdateDtTm field is modified as well. Therefore, we always must send a GET api/Deployments request first to fetch the details of the deployment and then use the received details as the body for the POST request to successfully modify the deployment. Using an invalid (past time) UpdateDtTm value will give a 400 Bad Request error.

Let’s proceed to learn how we can schedule jobs on the server using APIs.

3.6. Scheduling Jobs

3.6.1. Scheduling Jobs using ‘POST api/Schedule’ API example

In this section, we are scheduling the previously created deployment using the ‘POST api/Schedule’ API.

This API’s Request Body requires the schedule configuration information, i.e., Schedule Name, Schedule Type, Frequency, Activate State, Server Info, etc.

A sample JSON is attached here for reference.

Let’s create the schedule called Schedule_Testing, which runs daily, with schedule type deployment, an active state as True, etc.

Sending the request shows a 200 OK status response.

If we go to Server > Job Schedules, in the scheduler window, we can see a schedule called Schedule_Testing with the following properties: Schedule Job Id is 4, with Schedule Type as Deployment, running at Frequency daily has been created.

Note: Like the deployment POST API, this POST api/Schedule endpoint can also be used for modification of existing schedules.

Each time we update an existing schedule the UpdateDtTm field is modified as well. Therefore, we always have to send a GET api/Schedules or a GET /api/Schedule/:scheduleId request first to fetch the details and then use the received details as the body for the POST request to successfully modify a schedule.

Note: Using an invalid (past time) UpdateDtTm value will give a 400 Bad Request error.