Runtime APIs

Learn about the various APIs you can use to create, manage, and configure integration runtimes.

Runtime Management APIs

The Runtime Management APIs allow you to create and manage runtimes. For more information on runtime management, see Register Edge Runtimes, Integartion Runtimes Management 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: The following errors appear when,

    • 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

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

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

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 assocaite 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

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

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

Parameters

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

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/<{instanceID}>/ping

Parameters

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

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/<{instanceID}>

Parameters

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.

Runtime Configuration APIs

The Runtime Configuration APIs allow you to manage global configurations of a runtime. The following configurations are supported:

Important

Extended Settings

GET - List All Extended Settings

Allows you to retrieve names of all extended settings configured for Cloud Designtime.

Usage: Cloud Designtime

URL

../default/configurations/settings

Parameters

None

Request

None

Response

[
    {
        "assetId": "watt.server.coder.responseAsXML",
        "type": "settings"
    },
    {
        "assetId": "watt.client.data.maxToStringLength ",
        "type": "settings"
    }
]

GET - Get Extended Setting Configuration

Allows you to retrieve the value of a setting.

Usage: Cloud Designtime, Cloud Runtime, Edge Runtime

URL

../<runtime-alias>/configurations/settings/<asset-id>

Parameters

Request

None

Response

{
    "propertyKey": "watt.server.coder.responseAsXML",
    "value": "true"
}

PUT - Set Extended Setting Configuration

Allows you to set a new value for the extended setting. This value is not updated immediately unless you run the Synchronize Extended Setting Configuration API or set the updateRuntime value to true.

Usage: Cloud Designtime, Cloud Runtime, Edge Runtime

URL

../<runtime-alias>/settings/configurations/<asset-id>?updateRuntime=(true|false)

Parameters

Request Headers

Content-Type: application/json

Request Body

{
  "value": "false"
}

Response

POST - Synchronize Extended Setting Configuration

Allows you to synchronize the configured setting with the runtime.

Usage: Cloud Designtime, Cloud Runtime, Edge Runtime

URL

../<runtime-alias>/configurations/settings/<asset-id>/sync

Parameters

Request

None

Response

{
    "code": 0,
    "description": "The synchronization process has started. Check the <runtime-alias> for more details later."
}

Global Variables

GET - List Global Variables

Allows you to retrieve names of all global variables configured for Cloud Designtime.

Usage: Cloud Designtime

URL

../default/globalvariable

Parameters

None

Request Headers

Content-Type: application/json

Request Body

None

Response

[
    {
        "assetId": "globalvariable.OnPremiseISPkg.username",
        "displayName": "username",
        "type": "globalvariable"
    },
    {
        "assetId": "globalvariable.OnPremiseISPkg.Password",
        "displayName": "Password",
        "type": "globalvariable"
    }
]

PUT - Update Global Variables

Allows you to set a new value for the global variable in Cloud Designtime. This value is not updated immediately unless you run the Synchronize Global Variables API or set the updateRuntime value to true.

Usage: Cloud Designtime, Edge Runtime

Note
Global variable can only be updated in the Cloud Designtime. To use global variable in an Edge Runtime, you must run the Override Global Variables API for the Edge Runtime and sync the value on that runtime.

URL

/default/globalvariable/?updateRuntime=(true|false)

Parameters

Request Headers

Content-Type: application/json

Request Body

{
    "properties":
	[
        {
            "propertyKey": "globalvariable.OnPremiseISPkg.abc.value",
            "value": "avc1"
        }
    ]
}

Calling ../default/globalvariable/globalvariable.OnPremiseISPkg.abcAPI with above value updates the value of globalvariable.OnPremiseISPkg.abc global variable in the Cloud Designtime.

Response

PATCH - Override Global Variables

Allows you to override values of a global variable for a particular Edge Runtime. It must always be invoked for a runtime other than Cloud Designtime or Cloud Runtime. Like create or update APIs, the overridden values are not immediately updated in the runtime, unless the updateRuntime value is set to true or the Synchronize Global Variable API is run.

Usage: Edge Runtime

Note
If a global variable must be brought to a Edge Runtime, then you must first run Override Global Variable API for that runtime and then run the Synchronize Global Variable API for the Edge Runtime.

URL

../<runtime-alias>/globalvariable/?updateRuntime=(true|false)

Parameters

Request Headers

Content-Type: application/json

Request Body

{
    "properties":
	[
        {
            "propertyKey": "globalvariable.OnPremiseISPkg.abc.value",
            "value": "avc1"
        }
    ]
}

Calling ../MyEdgeServer/globalvariable/globalvariable.OnPremiseISPkg.abc API with above would update value of globalvariable.OnPremiseISPkg.abc in the MyEdgeServer runtime.

Response

POST - Synchronize Global Variables

Allows you to synchronize global variable with a runtime. This ensures that the global variable is created or updated on the runtime.

Usage: Cloud Designtime, Cloud Runtime, Edge Runtime

URL

..//globalvariable//sync

Parameters

Request Headers

Content-Type: application/json

Request Body

Calling ../MyEdgeServer/globalvariable/globalvariable.OnPremiseISPkg.abc/sync API synchronizes globalvariable.OnPremiseISPkg.abc value with MyEdgeServer.

Response

    {
        "code": 0,
        "description": "The synchronization process has started. Check the <runtime-alias> for more details later."
    }

JNDI Aliases

JNDI aliases can be created or updated only in the cloud runtime.

GET - List JNDI Aliases

Allows you to retrieve names of all JNDI settings for Cloud Designtime.

Usage: Cloud Designtime

URL

../default/configurations/jndi

Parameters

None

Request

None

Response

[
    {
        "assetId": "DEFAULT_IS_JNDI_PROVIDER",
        "type": "jndi"
    },
    {
        "assetId": "LocalJNDI",
        "type": "jndi"
    }
]

POST - Create JNDI Alias

Allows you to create a JNDI alias for a Cloud Designtime. JNDI Alias is not created immediately on the Cloud Designtime unless updateRuntime is set to true or Synchronize JNDI Alias with runtime API is run.

Note
JNDI alias can be created only in the Cloud Designtime. To use JNDI alias in an Edge Runtime, you must run the Override JNDI Alias API for a runtime and sync the alias on that runtime.

URL

../default/configurations/jndi/<asset-id>?updateRuntime=(true|false)

Parameters

Request Headers

{
  Content-Type: application/json
}

Request Body

{
    "properties": [
        {
            "propertyKey": "description",
            "value": "Connection to local UM"
        },
        {
            "propertyKey": "initialContextFactory",
            "value": "com.pcbsys.nirvana.nSpace.NirvanaContextFactory"
        },
        {
            "propertyKey": "providerURL",
            "value": "<UMRealmURL>"
        },
        {
            "propertyKey": "securityPrincipal",
            "value": "<Username>"
        },
        {
            "propertyKey": "securityCredentials",
            "value": "<Password>"
        }
    ]
}

Response

PUT - Update JNDI Alias

Allows you to update the values of a JNDI alias in Cloud Designtime. These values are not updated immediately in the Cloud Designtime unless updateRuntime is true or the Synchronize JNDI Alias with runtime API is run.

Usage: Cloud Designtime

URL

../default/configurations/jndi/<asset-id>?updateRuntime=(true|false)

Parameters

Request Headers

{
    Content-Type: application/json
}

Request Body

{
    "properties": [
        {
            "propertyKey": "description",
            "value": "LocalJNDI_updated"
        }
    ]
}
Note
Calling the ../default/configurations/jndi/LocalJNDI API with the mentioned details updates the description of LocalJNDI in the Cloud Designtime.

Response

PATCH - Override JNDI Alias

Allows you to override JNDI alias for a particular Edge Runtime. Like create or update APIs, the overridden values are not immediately displayed on the runtime, unless the updateRuntime value is set to true or the Synchronize JNDI Alias with runtime API is run.

Usage: Edge Runtime

Note
The Override JNDI Alias API must be invoked atleast once for a runtime other than the Cloud Designtime for JNDI alias to be available in that runtime. If no properties have to be overridden, then the Override JNDI Alias API must be invoked with an empty request body.

URL

../<runtime-alias>/configurations/jndi/<asset-id>?updateRuntime=(true|false)

Parameters

Request Headers

{
  Content-Type: application/json
}

Request Body

{
    "properties": [
        {
            "propertyKey": "description",
            "value": "JNDI_updated"
        }
    ]
}
Note
Calling ../MyEdgeServer/configurations/jndi/LocalJNDI API with the mentioned details overrides the description of LocalJNDI connection for MyEdgeServer runtime.

Response

POST - Synchronize JNDI Alias

Allows you to synchronize JNDI alias with a runtime. This ensures that the JNDI alias is created or updated on the runtime.

Usage: Cloud Designtime, Cloud Runtime, Edge Runtime

URL

../<runtime-alias>/configurations/jndi/<asset-id>/sync

Parameters

Request

Calling ../MyEdgeServer/configurations/jndi/LocalJNDI API with mentioned details updates the description of LocalJNDI in the MyEdgeServer runtime.

Response

{
    "code": 0,
    "description": "The synchronization process has started. Check the <runtime-alias> for more details later."
}

JMS Aliases

JMS aliases can only be created or updated in the Cloud Designtime.

GET - List JMS Aliases

Allows you to retrieve all JMS aliases present on the Cloud Designtime.

Usage: Cloud Designtime

URL

../default/configurations/jms

Parameters

None

Request

None

Response

[
    {
        "assetId": "DEFAULT_IS_JMS_CONNECTION",
        "type": "jms"
    },
    {
        "assetId": "PE_NONTRANSACTIONAL_ALIAS",
        "type": "jms"
    }
    {
        "assetId": "jmsLDS2",
        "type": "jms"
    }
]

POST - Create JMS Alias

Allows you to set a new JMS alias for the Cloud Designtime. JMS alias is not created immediately on the Cloud Designtime unless updateRuntime is true or the Synchronize JMS Alias with runtime API is run.

Note
JMS alias can be created only in the Cloud Designtime. To use JMS alias in an Edge Runtime, you must run the Override JMS Alias API for a runtime and sync the alias on that runtime.

URL

../default/configurations/jms/<asset-id>?updateRuntime=(true|false)

Parameters

Request Headers

{
    Content-Type: application/json
}

Request Body

{
    "properties": [
        {
            "propertyKey": "description",
            "value": "My local JMS connection"
        },
        {
            "propertyKey": "clientID",
            "value": "LOCAL_JMS_CLIENT"
        },
        {
            "propertyKey": "user",
            "value": "<username>"
        },
        {
            "propertyKey": "password",
            "value": "<password>"
        },
        {
            "propertyKey": "jndi_jndiAliasName",
            "value": "LocalJNDI"
        },
        {
            "propertyKey": "jndi_connectionFactoryLookupName",
            "value": "LocalFactory"
        }
    ]
}

Response

PUT - Update JMS Alias

Allows you to set new changes to the values of an existing JMS alias in the Cloud Designtime. These values are not displayed in the Cloud Designtime unless the updateRuntime value is set to true or the Synchronize JMS Alias with runtime API is run.

Note
JMS alias can only be updated in the Cloud Designtime. To use JMS alias in an Edge Runtime, you must run the Override JMS Alias values API for a runtime and sync the alias on that runtime.

Usage: Cloud Designtime

URL

../default/configurations/jms/<asset-id>?updateRuntime=(true|false)

Parameters

Request Headers

{
  Content-Type: application/json
}

Request Body

{
 "properties": 
 [
    {
        "propertyKey": "description",
        "value": "Updated JMS alias description"
    }
 ]
}
Note
Calling the ../default/configurations/jms/LocalJMS API with the mentioned details updates the description of LocalJMS in the Cloud Designtime.

Response

PATCH - Override JMS Alias

Allows you to override values of a JMS alias for a particular Edge Runtime. Like create or update APIs, overridden values are not immediately displayed on the runtime, unless the updateRuntime value is set to true or Synchronize JMS Alias with runtime API is run.

Usage: Edge Runtime

Note
The Override JMS Alias API must be invoked atleast once for a runtime other than the Cloud Designtime for JMS alias to be available in that runtime. If no properties need to be overridden, then the Override JMS Alias API must be invoked with an empty request body.

URL

../<runtime-alias>/configurations/jms/<asset-id>

Parameters

Note
JMS alias values must only be overridden for runtimes other than the cloud runtime.

Request Headers

{
  Content-Type: application/json
}

Request Body

{
  "properties":
     [
        {
            "propertyKey": "description",
            "value": "Updated JMS alias description for MyEdgeServer"
        }
     ]
}
Note
Calling ../MyEdgeServer/configurations/jms/LocalJMS API with the mentioned details updates the description of LocalJMS in the MyEdgeServer runtime.

Response

POST - Synchronize JMS Alias

Allows you to synchronize JMS alias with a runtime. This ensures that the JMS alias is created or updated on the runtime.

Usage: Cloud Designtime, Cloud Runtime, Edge Runtime

URL

../<runtime-alias>/configurations/jms/<asset-id>/sync

Parameters

Request

Calling ../MyEdgeServer/configurations/jms/LocalJMS API with the mentioned details updates the description of LocalJMS in MyEdgeServer runtime.

Response

{
    "code": 0,
    "description": "The synchronization process has started. Check the <runtime-alias> for more details later."
}

PATCH - Enable/Disable JMS Alias

Allows you to enable or disable a JMS alias on a runtime. Unlike other API calls, the Enable/Disable JMS Alias API applies the state immediately on the runtime.

Usage: Cloud Designtime, Cloud Runtime, Edge Runtime

URL

../<runtime-alias>/configurations/jms/<asset-id>/properties/state

Parameters

Request Headers

{
  Content-Type: application/json
}

Request Body

{
  "enabled": "<true|false>"
}

Calling ../MyEdgeServer/configurations/jms/LocalJMS/properties/state API with enabled set to false in the mentioned payload, disables the LocalJMS in the MyEdgeServer runtime.

Response

{
    "code": 0,
    "description": "Asset state was updated successfully. The synchronization process has started. Check the <runtime-alias> for more details later."
}