APIs in Integration runtime management

Manage your webMethods Integration runtime environment by using APIs.

Important:
  • All runtimes use the base URL https://host/apis/v1/rest/control-plane/runtimes.
  • For authentication, pass X-INSTANCE-API-KEY as a header. The value of X-INSTANCE-API-KEY is the API key that is generated by the admin user for your instance.
  • Status Codes
    • 400 Bad request - Displayed when incorrect runtime details are provided.
    • 401 Unauthorized - Displayed when you do any actions on a runtime without being its owner.
    • 403 Forbidden - Displayed when you access the runtime for which you do not have permission.
    • 500 - Displayed when the runtime is not reachable or does not respond.

You can use the runtime management APIs to create and manage runtimes. For more information on runtime management, see Registering edge runtimes and Managing runtime states.

GET - List runtimes

Retrieves the list of all runtimes along with the default Cloud Designtime and Cloud Runtime details also. The instances that are associated with runtimes are not listed by default. If you want to view the instances, include the parameter includeInstances and set it to true.

URL
../runtimes/
Parameters
  • includeInstances - 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. False is the default setting.
Request headers
Content-Type: application/json
X-INSTANCE-API-KEY: <genertaed API key>
Request body
None
Response
If the request is successful, you receive the HTTP 200 OK 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

Retrieves the details of a specific runtime.

URL
../<runtimeAlias>?includeInstances=<true>
Parameters
  • runtimeAlias - Alias (alternative name) that is used to represent a runtime.
  • includeInstances - Specify one of the following values.
    • True - Displays the specific runtime details along with instance information. True is the default setting.
    • False - Displays the runtime details without any instance information.
Request headers
Content-Type: application/json
X-INSTANCE-API-KEY: <genertaed API key>
Request body
None
Response
  • If the request is successful, you receive the HTTP 200 OK status response code.
  • If includeInstances=<true>, the instance details are displayed in the response code.
        {
    "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>, the instance details are not displayed in the response code.
    {
    "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, the unauthorized error is displayed in the response.
    {
	"message":	
	{
		"code": -1,
		"description": "401-Unauthorized"
	}
}

POST - Register runtimes

Register a new logical entity for a runtime. This entity is not yet ready to do any operations. Pair the runtime to use it for operations. If you do not pair the runtime, the runtime card is created and is in offline state on the home page. For more information about pairing, see Pair runtime instance.

URL
../runtimes/
Parameters
  • name - Name of the runtime.
  • description - Short description about the runtime.
  • visibility - Specify one of the values:
    • Public - All users can access the runtime.
    • Private - Only the owner who created the runtime can access the runtime. Private 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
X-INSTANCE-API-KEY: <genertaed API key>
Response
If the request is successful, you receive the HTTP 201 Created status response code.
{
    "name": "SampleEdge_1",
    "agentID": "5c81755566b44f7089085803f4b9be10",
    "createdDate": 1733373434260
}

POST - Pair runtime instances

Generates a pairing token for a runtime instance. Pairing token can be used to associate the runtime instance 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
X-INSTANCE-API-KEY: <genertaed API key>
Request body
None
Response

If the request is successful, you receive the HTTP 200 OK 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/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/aim/msr-edge-runtime:latest"
}

PUT - Update runtimes

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
X-INSTANCE-API-KEY: <genertaed API key>
Request body
{
  "description":"[optional runtime Description for self-reference]"
}
Response

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

POST - Enable or disable runtimes

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
X-INSTANCE-API-KEY: <genertaed API key>
Request body
None
Response
If the request is successful, you receive the HTTP 200 OK status response code.

POST - Ping runtimes

Ping a runtime to verify its availability.

URL
../<runtimeAlias>/ping
Parameters
runtimeAlias - Alias (alternative name) that is used to represent a runtime.
Request headers
Content-Type: application/json
X-INSTANCE-API-KEY: <genertaed API key>
Request body
None
Response
If the request is successful, you receive the HTTP 200 OK status response code.
{
  "$status": "success"
}

POST - Ping runtime instances

Ping a runtime instance to verify its availability.

URL
../<runtimeAlias>/instances/<instanceID>/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
X-INSTANCE-API-KEY: <genertaed API key>
Request body
None
Response

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

{
  "$status": "success"
}

DELETE - Deregister runtimes

Deregister edge runtimes if you do not want to use them in the future. Deregistering an edge runtime removes all instances that are associated with that edge runtime. The runtime is no longer available on the home page. However, the instances continue running in your environment, but they cannot 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
X-INSTANCE-API-KEY: <genertaed API key>
Request body
None
Response
If the request is successful, you receive the HTTP 204 No Content status response code.

DELETE - Remove runtime instances

Delete an instance of an edge runtime.

URL
../<runtimeAlias>/instances/<instanceID>
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
X-INSTANCE-API-KEY: <genertaed API key>
Request body
None
Response
If the request is successful, you receive the HTTP 204 No Content status response code.