Runtime Management APIs

The Runtime Management APIs allow you to create and manage runtimes. For more information on runtime management, see Register Edge Runtimes and Integration Runtimes Access Privileges.

Important:

  • All runtimes use the Base URL, https://host/apis/v1/rest/control-plane/runtimes.

  • All runtime APIs use Basic Tenant authentication for Authorization.

  • Status Codes:
    • 400 Bad request: Incorrect runtime details are provided.
    • 401 Unauthorized: Perform any actions on a runtime without being its owner.
    • 403 Forbidden: Permission is not available for you to access the runtime.
    • 500: Runtime is not reachable or does not respond.

GET - List Runtimes

Allows you to retrieve the list of all runtimes including the default Cloud Designtime and Cloud Runtime details. The instances associated with runtimes are not listed by default. If you want to view even them, include the parameter includeInstances and set it to true.

URL

../runtimes/

Parameters

  • includeInstances: [Optional] Specify one of the following values:

    • true: Displays the specific runtime details along with instance information.

    • false: Displays the runtime details without any instance information. This is the default setting.

Request Headers

Content-Type: application/json

Request Body

None

Response

If the request is successful, you receive the HTTP 200 OK success status response code.

[
{
    "agentID": "1ba0a988c99d11ef9cd20242ac120002",
	"agentGroup": "default",
    "name": "MyEdge1",
    "description": "Edge server running on local.",
    "createdDate": 1735796517000,
    "modifiedDate": 1735796839000,
    "status": "Running",
    "permission": [
        "MANAGE",
        "ACCESS"
    ],
    "visibility": "PRIVATE",
    "owner": {
        "fullName": "webMethodsIntegration Administrator",
        "userId": "6173cacbf3f64dc5aede0691f7479b62"
    }
},
{
    "agentID": "38a748d4c99d11ef9cd20242ac120002",
    "agentGroup": "default",
    "name": "MyEdge2",
    "description": "Edge server running on local",
    "createdDate": 1735886338000,
	"modifiedDate": 1735886357000,
    "status": "Running",
    "permission": [
        "MANAGE",
        "ACCESS"
    ],
    "visibility": "PRIVATE",
    "owner": {
        "fullName": "webMethodsIntegration Administrator",
        "userId": "6173cacbf3f64dc5aede0691f7479b62"
    }
}
]

GET - Get Runtimes

Allows you to retrieve the details of a specific runtime.

URL

../<runtimeAlias>?includeInstances=<true>

Parameters

  • runtimeAlias: Alias (alternative name) that is used to represent a runtime.

  • includeInstances: [Optional] Specify one of the following values:

    • true: Displays the specific runtime details along with instance information. This is the default setting.

    • false: Displays the runtime details without any instance information.

Request Headers

Content-Type: application/json

Request Body

None

Response

If the request is successful, you receive the HTTP 200 OK success status response code.

If includeInstances=<true> :

    {
    "agentID": "4dd48e1a90294421b34f6346a272ab3e",
    "agentGroup": "default",
    "name": "LocalWSLEdge",
    "description": "Edge server running on local WSL",
    "createdDate": 1735796517000,
    "modifiedDate": 1735796839000,
    "status": "Running",
    "instances": [
        {
            "instanceID": "9973c9bf5c99",
            "status": "Unknown"
        }
    ],
    "permission": [
        "MANAGE",
        "ACCESS"
    ],
    "visibility": "PRIVATE",
    "owner": {
        "fullName": "webMethodsIntegration Administrator",
        "userId": "6173cacbf3f64dc5aede0691f7479b62"
    }
}

If includeInstances=<false> :

{
    "agentID": "4dd48e1a90294421b34f6346a272ab3e",
    "agentGroup": "default",
    "name": "LocalWSLEdge",
    "description": "Edge server running on local WSL",
    "createdDate": 1735796517000,
    "modifiedDate": 1735796839000,
    "status": "Running",
    "permission": [
        "MANAGE",
        "ACCESS"
    ],
    "visibility": "PRIVATE",
    "owner": {
        "fullName": "webMethodsIntegration Administrator",
        "userId": "6173cacbf3f64dc5aede0691f7479b62"
    }
}

If you are not the owner of a runtime:

{
	"message":	
	{
		"code": -1,
		"description": "401-Unauthorized"
	}
}

POST - Register Runtimes

Allows you to register a new logical entity for a runtime. This entity is not yet ready to perform any operations. You must pair in order to use this runtime. In the Integration Runtimes page, the runtime card is created and it is in offline state.

URL

../runtimes/

Parameters

  • name: Name of the runtime.

  • description: [Optional] Short description about the runtime.

  • visibility: [Optional] Specify one of the values:

    • Public: The runtime is accessible to all users.
    • Private: The runtime can be accessed by only the owner who created the runtime. This is the default value.

Request

{
  "name":"[runtime name]",
  "description":"[optional runtime Description for self-reference]",
   "visibility":"[optional private or public]"
}

Request Headers

Content-Type: application/json

Response

If the request is successful, you receive the HTTP 201 Created success status response code.

{
    "name": "SampleEdge_1",
    "agentID": "5c81755566b44f7089085803f4b9be10",
    "createdDate": 1733373434260
}

POST - Pair Runtime Instances

Allows you to generate a pairing token for a runtime instance. Pairing token can be used to bring up the new runtime instance and associate it with the logical entity. This API also provides the docker run command that can be used to start a runtime instance in a container.

URL

../<runtimeAlias>/instances/new-pairing-request

Parameters

  • runtimeAlias: Alias (alternative name) that is used to represent a runtime.

Request Headers

Content-Type: application/json

Request Body

None

Response

If the request is successful, you receive the HTTP 200 OK success status response code.

{
    "agentId": "14fe873f37f2495fb26a78d3e037db31",
    "agentName": "testedgepub1",
    "env": {
        "SAG_IS_CLOUD_REGISTER_URL": "https://host",
        "SAG_IS_CLOUD_REGISTER_TOKEN": "ba51541ca8884b73850793c65ed51799d76e10bc496d4cb09620431287071d6f",
        "SAG_IS_EDGE_CLOUD_ALIAS": "EdgeRuntime_87071d6f"
    },
    "imageRegistryURL": "iregistry.infra.webmethods.io/aim/msr-edge-runtime:latest",
    "dockerRunCommand": "docker run -p 5555:5555 -d -e SAG_IS_CLOUD_REGISTER_URL=https://host -e SAG_IS_EDGE_CLOUD_ALIAS=EdgeRuntime_testedgePub1 -e SAG_IS_CLOUD_REGISTER_TOKEN=ba51541ca8884b73850793c65ed51799d76e10bc496d4cb09620431287071d6f --name=testedgePub1_87071d6f iregistry.infra.webmethods.io/aim/msr-edge-runtime:latest"
}

PUT - Update Runtimes

Allows you to update the description of a runtime.

URL

../{runtimeAlias}

Parameters

  • runtimeAlias: Alias (alternative name) that is used to represent a runtime.

Request Headers

Content-Type: application/json

Request Body

{
  "description":"[optional runtime Description for self-reference]"
}

Response

If the request is successful, you receive the HTTP 200 OK success status response code.

POST - Enable/Disable Runtimes

Allows you to enable or disable a runtime.

URL

  • For enabling a runtime: ../<runtimeAlias>/enable

  • For disabling a runtime: ../<runtimeAlias>/disable

Parameters

  • runtimeAlias: Alias (alternative name) that is used to represent a runtime.

Request Headers

Content-Type: application/json

Request Body

None

Response

If the request is successful, you receive the HTTP 200 OK success status response code.

POST - Ping Runtimes

Allows you to ping a runtime to verify it's availabilty.

URL

../<runtimeAlias>/ping

Parameters

  • runtimeAlias: Alias (alternative name) that is used to represent a runtime.

Request Headers

Content-Type: application/json

Request

None

Response

If the request is successful, you receive the HTTP 200 OK success status response code.

{
  "$status": "success"
}

POST - Ping Runtime Instances

Allows you to ping a runtime instance to verify it's availabilty.

URL

../<runtimeAlias>/instances/<>/ping

Parameters

  • runtimeAlias: Alias (alternative name) that is used to represent a runtime.

  • instanceID: Unique identification number of the instance.

Request Headers

Content-Type: application/json

Request Body

None

Response

If the request is successful, you receive the HTTP 200 OK success status response code.

{
  "$status": "success"
}

DELETE - Deregister Runtimes

Allows you to deregister edge runtimes if you do not want to use them in the future. Deregistering an edge runtime removes all instances associated with that edge runtime. The runtime is no longer available in the Integration Runtimes page. However, the instances still continue running in your environment, but they would not be able to communicate with the control plane.

URL

../<runtimeAlias>

Parameters

  • runtimeAlias: Alias (alternative name) that is used to represent a runtime.

Request Headers

Content-Type: application/json

Request Body

None

Response

If the request is successful, you receive the HTTP 204 No Content success status response code.

DELETE - Remove Instances

Allows you to delete a particular instance of an edge runtime.

URL

../<runtimeAlias>/instances/<>

Parameters

  • runtimeAlias: Alias (alternative name) that is used to represent a runtime.

  • instanceID: Unique identification number of the instance.

Request Headers

Content-Type: application/json

Request Body

None

Response

If the request is successful, you receive the HTTP 204 No Content success status response code.