Hello world

This tutorial shows you how to create your first user-defined API. You will create a simple API that, upon execution, will return "Hello world!". The content and screenshots for this tutorial have been created in DataMiner version 10.3.9.

Important

Before you start this tutorial, take a look at the prerequisites.

Overview

• Step 1: Create an Automation script solution
• Step 2: Create the Automation script
• Step 3: Create an API token
• Step 4: Create the API Definition
• Step 5: Trigger the API using Postman

Step 1: Create an Automation script solution

While you could develop the Automation script in Cube, creating an Automation script solution in Visual Studio will give you the advantage of having access to all the features of Visual Studio and DIS. If you also use a version control system like Git, this will also enable versioning and make collaboration possible.

• Visual Studio 2022
• Visual Studio 2019

To create an Automation script solution:

1. In Visual Studio, select Create a new project.

2. Search for DataMiner User-Defined APIs Solution (Skyline Communications) in the template search box and click Next.

   

3. Use "DataMinerAPIs" as the name for your solution, so you can reuse this solution for any future API scripts.

4. Choose a location to save the Automation script solution and click Next.

   

5. Specify HelloWorldAPI as the name of your Automation script, fill in your name as the author, and click Create.

   

Step 2: Create the Automation script

The logic of your API is in an Automation script. This processes input arguments, executes logic, and returns a response. In this example, no input is processed, and no logic is executed. The API will only return "Hello world!" to the user.

• Visual Studio 2022
• Visual Studio 2019

Write the API logic

The goal of this tutorial is to have "Hello world!" returned when the API script is triggered. To configure this, you need to replace the default "Succeeded" string provided by the snippet with the "Hello world!" string. The resulting and final state of the script should look like this:

namespace HelloWorldAPI_1
{
    using Skyline.DataMiner.Automation;
    using Skyline.DataMiner.Net.Apps.UserDefinableApis;
    using Skyline.DataMiner.Net.Apps.UserDefinableApis.Actions;

    public class Script
    {
        [AutomationEntryPoint(AutomationEntryPointType.Types.OnApiTrigger)]
        public ApiTriggerOutput OnApiTrigger(IEngine engine, ApiTriggerInput requestData)
        {
            return new ApiTriggerOutput
            {
                ResponseBody = "Hello world!",
                ResponseCode = (int)StatusCode.Ok,
            };
        }
    }
}

Publish the script

When the API script is complete, it needs to be published to the DataMiner System. You can do so using the built-in publish feature of DIS. Make sure that DIS can connect to the DataMiner System you want to upload your script to. You will need to edit the DIS settings so the DMA is selectable.

1. In the Solution Explorer, double-click HelloWorldAPI.xml.

   

2. At the top of the code window, click the arrow next to the Publish button, and select the DataMiner System you want to upload the script to.

   

Step 3: Create an API token

To access the API, you will need an API token.

1. Open DataMiner Cube, and log into your DataMiner System.

2. Go to System Center > User-Defined APIs.

3. Under Tokens, click Create

4. For the Name, enter "HelloWorldToken", and click Generate token.

   

5. Copy the generated secret to a safe location (e.g. a password manager).

   

   Important

   After closing this window, you will no longer be able to retrieve the secret. Make sure that the secret is saved somewhere safe. If it is lost, a new token will have to be created.

You should now be able to see the token in the Tokens table.

Step 4: Create the API Definition

The script and the token are now available in the DMS. The next step is to create an API definition that ties both together. This definition is also used to define the URL where this API will be available.

1. Open the Automation module in DataMiner Cube.

2. Open the HelloWorldAPI Automation script.

3. At the bottom of the screen, click the Configure API button.

   

4. Optionally enter a description for the API.

5. For the URL, enter "helloworld".

6. In the bottom Tokens pane, select the HelloWorldToken, which was created in the previous step.

7. Finally, click the Create button.

   

The API definition has now been created. Next to the API script, you should see an icon that indicates that this script is used by an API definition.

Step 5: Trigger the API using Postman

The API has now been fully configured. To ensure that it functions correctly, you can test the API using an API testing app like Postman.

Note

If this is the first time you use Postman, the app will ask you to create an account or sign in. You can create an account, but you can also continue using the try our lightweight API client button at the bottom of the screen.

1. Open Postman and click the + icon to create a new request.

   

2. In the URL field, enter https://HOSTNAME/api/custom/helloworld, replacing "HOSTNAME" with the hostname of the DataMiner Agent.

   

3. Go to the Authorization tab and select Bearer Token as Type.

   

4. In the Token field, enter the API token secret that you copied in step 3.

   

5. Finally, click the blue Send button on the right.

An HTTP GET request will now be sent to the API endpoint, which will trigger the API script. You should see the "Hello world!" message in the response section.

Tip

If the DMA is using SSL certificates that were not signed by an external certificate authority, you may receive a warning about SSL verification. If you trust the system, you can click Disable SSL verification to disable SSL verification and send the request again.