Skip to content

Onteon Control Center v2 API

General Rules

Request Body

In most cases, the request body is the GenericInputDTOV1 object represented as the following json object:

{
  "nodeManagerInputDTOS" : [ {
      "ip" : "localhost",
      "apiPort": 8030
    } ],
  "functionArguments" : {
   "appId" : "423335658743324782323213",
   "instanceId" : "af3b465544efb0cbac80d331",
   "command" : "traceroute"
  },
  "handlerArguments" : {
        "force" : true,
        "asynchronous" : true,
        "isChunkingOutput" : false,
        "referenceNumber" : "8945845783458972490759749058",
        "connectionTimeoutToCheckNodeManager" : 2000,
        "waitTimeBetweenOperationsOnNodeManagers" : 10000
    },
   "innerCommunicationProtocolArguments" : {
        "referenceNumber" : "8945845783458972490759749051",
        "asynchronous" : false
   }
}

The nodeManagerInputDTOS section is an array of Onteon Node Managers (NodeManagerInputDTOV1 object), on which the operation will be executed. Java representation of the NodeManagerInputDTOV1 object:

public class NodeManagerInputDTOV1 implements Serializable {

    private String id;
    private String name;
    private String ip;
    private String fqdn;
    private int apiPort;

}

The nodeManagerInputDTOS array can be an empty array only if there are filters set in the handlerArgument's filter section. The array must exist then, but it's size have to be 0 ([]).

The functionArguments is a section, which is responsible for passing arguments of the function, specified by the given endpoint (check in the API sections).

The handlerArguments is a section, which is responsible for controling the execution of the given endpoint. It uses the following flags:

  • force (true or false) - decide whether the request should be executed on those Onteon Node Managers passed in the nodeManagerInputDTOS, which are registered in the Onteon Control Center (false) or on either registered or unregistered (true).
  • asynchronous (true or false) - decide if the Onteon Control Center will await for the synchronous response (false) or just schedule an operation for asynchronous execution and receive 202 Accepted status with operation information (true). Later on, getting the status and results is done by special get status and get operation endpoints.
  • isChunkingOutput (true or false) - it is taken into consideration only for requests to the streaming-microservice in the operations, which can return chunks or a stream and only when asynchronous is set to false. It is especially useful for example while starting an application instance to get a real time output with a stream.
  • referenceNumber (32-character hexadecimal string) - it is a reference number, which is used for getting asynchronous operation's status and result. It should be set (if not, then it is auto-generated) if the asynchronous flag is set to true.
  • connectionTimeoutToCheckNodeManager (long) - defines how long, the handler will wait for TCP/IP connection with a single integer Node Manager to check it's availability using both fqdn and IP addresses. Default value is 5000ms (5s).
  • waitTimeBetweenOperationsOnNodeManagers (integer) - defines, how much delay should there be between executions on each Onteon Node Manager. Default value is 20000ms (20s).

The innerCommunicationProtocolArguments is a section of information about the transition protocol between Onteon Control Center and Onteon Node Manager (CDTP). It uses the following flags:

  • asynchronous (true or false) - decides if the communication between Onteon Control Center and Onteon Node Manager will be synchronous or asynchronous. If synchronous, Onteon Control Center awaits for the response from the Onteon Node Manager and then the results will be available on Onteon Control Center. If asynchronous, then operations are scheduled and their status and result can be checked by requests to the dedicated endpoints.
  • referenceNumber (32-character hexadecimal string) - it is a reference number, which is used for getting asynchronous operation's status and result. It should be set (if not, then it is auto-generated) if the asynchronous flag is set to true.

Response Body

In most cases, the response body is the GenericOutputDTOV1 object represented as the following json object:

{
    "nodeManagerOutputDTOS": [
        {
            "id": null,
            "name": null,
            "ip": "localhost",
            "fqdn": null,
            "apiPort": 8030,
            "wasScheduled": true,
            "wasError": false,
            "errorMessage": null,
            "errorStackTrace": null,
            "outputObject": {}
        }
    ],
    "functionArguments": {},
    "handlerArguments": {
        "force": true,
        "asynchronous": false,
        "connectionTimeoutToCheckNodeManager": 5000,
        "waitTimeBetweenOperationsOnNodeManagers": 20000
    },
    "wasScheduledInAsynchronousMode": false,
    "innerCommunicationProtocolArguments": {
        "referenceNumber": "8945845783458972490759749059",
        "asynchronous": false
    }
}

The nodeManagerOutputDTOS section is an array of Onteon Node Managers (NodeManagerOutputDTOV1 object), on which the operation was executed. Java representation of the NodeManagerOutputDTOV1 object:

public class NodeManagerOutputDTOV1 implements Serializable {

    private String id;
    private String name;
    private String ip;
    private String fqdn;
    private int apiPort;
    private boolean wasScheduled = false;
    private boolean wasError = false;
    private String errorMessage;
    private String errorStackTrace;
    private Object outputObject;

}

NodeManagerOutputDTOV1 object contains details of each operation on given Onteon Node Managers. If id was passed in request, then it will be filled in the response, if not - it will be empty (for force: true). If we did not pass some of the fields (id, name, ip, etc.) and force was set to false, Onteon Control Center will fill those fields in response.

NodeManagerOutputDTOV1 fields:

  • wasScheduled - tells if the operation was scheduled on the given Onteon Node Manager (if connection was obtained, operations were send to be executed and response came back)
  • wasError - tells if error ocurred during obtaining connection, sending operation or executing operation on Onteon Node Manager.
  • errorMessage - error message.
  • errorStackTrace - error stack trace, helps quicker details investigation.
  • outputObject - operation execution output from Onteon Node Manager.
  • functionArguments, handlerArguments, wasScheduledInAsynchronousMode, innerCommunicationProtocolArguments - confirmation of the fields sent in request.

Status 422 Response Body

{
  "errorMessage": "GenericInputDTO object is null",
  "errorMessageKey": "error-validation-message-key-0"
}

Status 500 Response Body

{
  "errorMessage": "an error ocurred during uploading file caused by:",
  "errorMessageKey": "upload-to-node-manager-message-key",
  "errorStackTrace": "java.lang.ArrayIndexOutOfBoundsException: Index 10 out of bounds for length 5\n\tat com.example.MyArrayClass.getElement(MyArrayClass.java:42)\n\tat com.example.MyArrayClass.processArray(MyArrayClass.java:30)\n\tat com.example.Main.main(Main.java:15)"
}

Response codes

HTTP response codes (general schema for most requests, details available in API sections):

  • 202 - Accepted for asynchronous executions.
  • 207 - Multistatus for synchronous executions.
  • 422 - Request parameters validation error.
  • 405 - HTTP method not allowed.
  • 500 - Internal Server Error - general error with details from the method, where it ocurred.

Headers

While calling the API, Onteon Control Center requires request headers.

Headers required in all the requests:

Headers required in credentials (token and identities) rotation requests:

Not required, but recommended headers for logs auditing:

Onteon-User-Name

Onteon-User-Name header stores name of the user / API client. It is used for logs auditing purposes (finding operations in logs by username). It is required in all the requests.

Onteon-Correlation-ID

Onteon-Correlation-ID header store id of the request. Id must be a 32-character hexadecimal string.It is used for logs auditing purposes (finding operations in logs by correlation id). It is required in all the requests.

Authorization

Authorization header is a string with prefix Bearer and OCC API Token (for example Bearer a9f3c2e8b47d6a1f09ce5d24b8a7e3f2). It is used for security purposes. If this header is invalid, then the response is 401 Unathorized. It is required in all the requests. Default value: a9f3c2e8b47d6a1f09ce5d24b8a7e3f2.

Refresh-Token

Refresh-Token header is a string with OCC API Secure Token (for example a9f3c2e8b47d6a1f09ce5d24b8a7e3f2). It is used for security purposes in the credentials (tokens and identities) rotation. It is important to remember that opposed to Authorization header, this one should not start with the Bearer prefix. If this header is invalid, then the response is 401 Unathorized. Default value: 7e4a9c2f1b8d0e6c5a3f9d2b4e7a1c8c.

Onteon-Client-MAC

Onteon-Client-MAC header stores the MAC address(es). If there are more than one, then they should be split by commas (for example 3A:7F:91:C2:4B:E8 or 3A:7F:91:C2:4B:E8,8D:22:5C:A1:9F:73). This header is not required, but recommended for logs auditing purposes (finding operations in logs by MAC).

Onteon-Client-IPv4

Onteon-Client-IPv4 header stores the IPv4 address(es). If there are more than one, then they should be split by commas (for example 192.168.45.123 or 192.168.45.123,10.73.201.56). This header is not required, but recommended for logs auditing purposes (finding operations in logs by IPv4).

Onteon-Client-IPv6

Onteon-Client-IPv6 header stores the IPv6 address(es). If there are more than one, then they should be split by commas (for example 2001:0db8:85a3:0000:0000:8a2e:0370:9c21 or 2001:0db8:85a3:0000:0000:8a2e:0370:9c21,fe80:0000:0000:0000:7c3a:5bff:fe12:4d9a). This header is not required, but recommended for logs auditing purposes (finding operations in logs by IPv6).

Onteon-Client-FQDN

Onteon-Client-FQDN header stores the FQDN address. For example my-server.localhost This header is not required, but recommended for logs auditing purposes (finding operations in logs by FQDN).

Core Microservice API

Streaming Microservice API

Application Sequence

Upload and start application

Sequence for uploading and starting an application:

  1. Upload to Onteon Control Center - /_by_name/streaming-microservice/v1/occManagerHandler/uploadToLocalStore
  2. Upload to Onteon Node Manager - /_by_name/core-microservice/v1/transferManagerHandler/uploadToNodeManager
  3. Add new application - /_by_name/core-microservice/v1/applicationManagerHandler/addNewApplication
  4. Create application - /_by_name/core-microservice/v1/applicationManagerHandler/createApplication
  5. Create application instance - /_by_name/core-microservice/v1/applicationManagerHandler/createApplicationInstance
  6. Start application instance - /_by_name/streaming-microservice/v1/applicationManagerHandler/startApplicationInstance

Stop and remove application

Sequence for stopping and removing an application:

  1. Stop application instance - /_by_name/streaming-microservice/v1/applicationManagerHandler/stopApplicationInstance
  2. Terminate application instance - /_by_name/streaming-microservice/v1/applicationManagerHandler/terminateApplicationInstance
  3. Remove application instance - /_by_name/core-microservice/v1/applicationManagerHandler/removeApplicationInstance
  4. Remove application instance permanently - /_by_name/core-microservice/v1/applicationManagerHandler/removeApplicationInstancePermanently
  5. Remove application - /_by_name/core-microservice/v1/applicationManagerHandler/removeApplication
  6. Remove application permanently - /_by_name/core-microservice/v1/applicationManagerHandler/removeApplicationPermanently

Execute command on application instance

Synchronously execute command on application instance:

  1. Execute command on application instance - /_by_name/streaming-microservice/v1/applicationManagerHandler/executeCommandOnApplicationInstance

Asynchronously (handlerArguments - client -> Onteon Control Center) execute command on application instance:

  1. Execute command on application instance - /_by_name/streaming-microservice/v1/applicationManagerHandler/executeCommandOnApplicationInstance
  2. Check if operation result is available - /_by_name/core-microservice/v1/occManagerHandler/isStateCommandOnNodeManagers
  3. Get result from an operation - /_by_name/core-microservice/v1/occManagerHandler/getStateCommandOnNodeManagers

Asynchronously (handlerArguments - client -> Onteon Control Center and innerCommunicationProtocolArguments - Onteon Control Center -> Onteon Node Manager) execute command on application instance:

  1. Execute command on application instance - /_by_name/streaming-microservice/v1/applicationManagerHandler/executeCommandOnApplicationInstance
  2. Check if operation result is available - /_by_name/core-microservice/v1/occManagerHandler/isStateCommandOnNodeManagers
  3. Get result from an operation (validate if error ocurred) - /_by_name/core-microservice/v1/occManagerHandler/getStateCommandOnNodeManagers
  4. Get execution summary from Onteon Node Managers - /_by_name/core-microservice/v1/commandManagerHandler/getExecutionSummary

Scheduling Sequence

Upload and start application

  1. Upload to Onteon Control Center - /_by_name/streaming-microservice/v1/occManagerHandler/uploadToLocalStore
  2. Upload to Onteon Node Manager (with handlerArguments.asynchronous set to true) - /_by_name/core-microservice/v1/transferManagerHandler/uploadToNodeManager
  3. Check if upload finished (status 200 and response body true means operation finished) - /_by_name/core-microservice/v1/occManagerHandler/isStateUploadToNodeManagers.
  4. Check if upload was successful - /_by_name/core-microservice/v1/occManagerHandler/getStateUploadToNodeManagers
  5. Schedule a group of operations to create application, application instance and start it. Example request body:
{
  "nodeManagerInputDTOS" : [ {
    "ip" : "127.0.0.1",
    "apiPort" : 8030
  } ],
  "functionArguments" : {
    "listOfCommands" : [ {
      "functionName" : "addNewApp",
      "moduleName" : "app-manager",
      "parameters" : {
        "appVersion" : "1.0.0",
        "appShortName" : "simple-app",
        "appId" : "423335658743324782323213",
        "returnResultIfConditionsAreMet":true
      }
    }, {
      "moduleName" : "app-manager",
      "parameters" : {
        "appId" : "423335658743324782323213",
        "returnResultIfConditionsAreMet":true
      },
      "functionName" : "createApp"
    }, {
      "moduleName" : "app-manager",
      "parameters" : {
        "instanceId" : "af3b465544efb0cbac80d331",
        "appId" : "423335658743324782323213",
        "returnResultIfConditionsAreMet":true
      },
      "functionName" : "createInstance"
    }, {
      "moduleName" : "app-manager",
      "parameters" : {
        "instanceId" : "af3b465544efb0cbac80d331",
        "appId" : "423335658743324782323213",
        "returnResultIfConditionsAreMet":true
      },
      "functionName" : "startInstance"
    } ]
  },
  "handlerArguments" : {
    "force" : false,
    "referenceNumber" : "0025845783458972490759749059ae12",
    "waitTimeBetweenOperationsOnNodeManagers": 0
  },
  "innerCommunicationProtocolArguments" : {
    "referenceNumber" : "0025845783458972490759749059ae12"
  }
}
  1. Check if scheduled operations are complete - /_by_name/core-microservice/v1/occManagerHandler/isStateCommandOnNodeManagers
  2. Get results from execution - /_by_name/core-microservice/v1/occManagerHandler/getStateCommandOnNodeManagers
  3. Get execution summary from Onteon Node Managers - /_by_name/core-microservice/v1/commandManagerHandler/getExecutionSummary

Stop and remove application

  1. Schedule a group of operations to create application, application instance and start it. Example request body:
{
  "nodeManagerInputDTOS" : [ {
    "ip" : "127.0.0.1",
    "apiPort" : 8030
  } ],
  "functionArguments" : {
    "listOfCommands" : [ {
      "functionName" : "stopInstance",
      "moduleName" : "app-manager",
      "parameters" : {
        "appId" : "423335658743324782323213",
        "instanceId" : "af3b465544efb0cbac80d331",
        "returnResultIfConditionsAreMet":true
      }
    }, {
      "moduleName" : "app-manager",
      "parameters" : {
        "appId" : "423335658743324782323213",
        "instanceId" : "af3b465544efb0cbac80d331",
        "returnResultIfConditionsAreMet":true
      },
      "functionName" : "removeInstance"
    }, {
      "moduleName" : "app-manager",
      "parameters" : {
        "instanceId" : "af3b465544efb0cbac80d331",
        "appId" : "423335658743324782323213",
        "returnResultIfConditionsAreMet":true
      },
      "functionName" : "removeInstancePermanently"
    }, {
      "moduleName" : "app-manager",
      "parameters" : {
        "appId" : "423335658743324782323213",
        "returnResultIfConditionsAreMet":true
      },
      "functionName" : "removeApp"
    },

    {
      "moduleName" : "app-manager",
      "parameters" : {
        "appId" : "423335658743324782323213",
        "returnResultIfConditionsAreMet":true
      },
      "functionName" : "removeAppPermanently"
    }]
  },
  "handlerArguments" : {
    "force" : true,
    "referenceNumber" : "929458ad56ca046d4614d2fa",
    "waitTimeBetweenOperationsOnNodeManagers": 0
  },
  "innerCommunicationProtocolArguments" : {
    "referenceNumber" : "929458ad56ca046d4614d2fa"
  }
}
  1. Check if scheduled operations are complete - /_by_name/core-microservice/v1/occManagerHandler/isStateCommandOnNodeManagers
  2. Get results from execution - /_by_name/core-microservice/v1/occManagerHandler/getStateCommandOnNodeManagers
  3. Get execution summary from Onteon Node Managers - /_by_name/core-microservice/v1/commandManagerHandler/getExecutionSummary