Stubs REST API specification

The REST services for stubs are defined in IBM® Rational® Test Control Panel - Stubs REST API specification.

For general information about the REST API, see REST Services.

Compatibility with later versions

To improve the compatibility of clients of the REST API with later versions, you must not manually construct URLs, except for the Get a list of all stub definitions URL. URLs can be generated by resolving the relative href attributes that are provided in the XML. All href attributes must be resolved against the URL that they were returned from.

List of requests, grouped by resource type

Get a list of all stub definitions

URL RTCP_BASE_URL/rest/stubs/ . For example, https://mydefaultServer:5443/RTCP/rest/stubs/ .
Method GET
Parameters domain The name of the domain (required).
env The name of the environment (required).
stub The name of the stub. Do not specify this parameter if the ID parameter is specified (optional).
id The ID of the stub. Do not specify this parameter if the stub parameter is specified (optional).
comp The name of the lowest-level containing component for the stub (optional).
op The name of the containing operation for the stub (optional).
version The version of the stub (optional).
Returns 200 OK (but could return an empty list).
400 BAD REQUEST: If any required query parameters were missing, or if any parameters were invalid.
412 PRECONDITION FAILED: If the domain or environment could not be found.

Response body

<?xml version="1.0" encoding="UTF-8"?>
<stubs>
    <stub id="id" name="name" component="component name" version="1.0" href="relative URL" />
    <stub id="id" name="name" component="component name" 
operation="operation name" version="1.1" href="relative URL" />
    ...
</stubs>
href
URLs point to a stub definition, relative to RTCP_BASE_URL/rest/stubs/ . Construct href in the following format: domain/environment/project_repository/stub ID/ . For example, default/testENV/vapp6628408930409162330/-5d4e098e:15c3007c307:-7e2c/ .

Get a specific stub definition

URL Resolve the relative URL retrieved from the Get a list of all stub definitions response, relative to RTCP_BASE_URL/rest/stubs/ , as defined by section 5.2.2 of RFC 3986.
Method GET
Returns 200 OK
412 PRECONDITION FAILED: If the domain could not be found.

Response body

<?xml version="1.0" encoding="UTF-8"?>
<stub>
    <configuration href="relative URL to stub definition configuration" />
    <instances href="relative URL to stub instances list" />
</stub>

Start stub

URL Resolve the relative URL retrieved from the Get a list of all stub definitions response, relative to RTCP_BASE_URL/rest/stubs/ , as defined by section 5.2.2 of RFC 3986. This URI is the same as that for Get a specific stub definition.
Method POST
Returns 202 ACCEPTED: The stub will start in the background.
400 BAD REQUEST: If the request data could not be understood.
404 NOT FOUND: If the stub could not be found.
409 CONFLICT: If a stub is already running.
412 PRECONDITION FAILED: If the domain or environment could not be found. Or, if no agents are available to run the stub.
423 LOCKED: If the environment is locked by another user.

Request headers

X-User

If domain-level security is disabled, this setting can be used to specify the user who is starting the stub. This setting can be used to perform the operation through an already-obtained environment lock. For more information about environment locks, see Environments REST API specification.

.
Authorization
If domain-level security is enabled a security token must be passed as a HTTP Request header. For more information, see REST and Domain level security.
Content-Type
application/xml

Request data

<?xml version="1.0" encoding="UTF-8"?>
<start-stub>
	<configuration>
		<tags>
			<tag name="my tag 1" value="default value" />
			<tag name="my tag 2" value="" /> <!-- Default to empty string -->
			<tag name="my tag 3" /> <!-- Default to null -->
			...
		</tags>
	<behaviours>
		<behaviour name="behaviour instance name">
			<parameters>
				<parameter name="parameter name" value="default value" />
					...
			</parameters>
		</behaviour>
				...
	</behaviours>
	<logging level="DEFAULT|NONE|NORMAL|DEBUG" />
	<response-time distribution="FIXED|UNIFORM|GAUSSIAN" minimum="0" maximum="1000" />
	</configuration>
	<agents>
		<agent count="integer" id="id" host="host name or IP (as specified by agent)">
			<attributes>
				<attribute value="attribute name" />
					...
			</attributes>
		</agent>
	</agents>
	<force if="reused-agent" />
	<engine dedicated="true">
		<jvmOptions>
			<option>-Xmx512m</option>
			<option>-Dmy.option="my value"</option>
		</jvmOptions>
	</engine>
</start-stub>

To start the stub with default configuration, send the following request:

<?xml version="1.0" encoding="UTF-8"?>
<start-stub />
A description of the child elements that you can include follows:
  • The configuration element is as defined in Stub definition configuration, but with the actual values to use.
    • Child configuration elements are optional, and if omitted take their default values.
  • Agent element:
    • Omitting the agent element automatically selects an agent.
    • Agents can be specified by either of the following options:
      • An agent host, that uses the host attribute. The stubs are started on a single agent on that host. If both host and ID attributes are specified, host is used.
      • An agent ID, that uses the ID attribute. The stubs are started on a single agent on that host.
      • Agent attributes, by using the attributes element, and an agent count, by using the count attribute. The number that is specified in the count attribute determines how many agents the stub starts on. Only agents that match the attributes that are specified are used. If count is omitted, then it defaults to 1. If attributes are omitted, then the agents are not filtered by attributes.
    • Agent attributes, which are the values of the value attribute of the attribute elements, must not contain commas, and are case-insensitive.
    • Only one agent element can be used.
  • Force element:
    Use the force option to start the stub by attempting to ignore any warnings or errors that might occur.
    • force: To ignore all the problems that occur when you start the stub.
    • forceIf: Specify a space-separated list of problem identifiers to ignore when you start a stub.
    • forceUnless: Specify a space-separated list of problem identifiers to not ignore when you start a stub. If the parameter list is empty, the force setting is not considered and none of the errors are ignored.
    You can specify if a specific problem identifier must either be ignored or considered when the stub is started. The problem identifier parameters are:
    • agent-criteria-unsatisfied: Indicates that there were not enough agents available to run the stub or the specified agents were not found.
    • reused-agent: Indicates that the selected agent is already running that stub. Running multiple instances of that stub at the same time on the same agent does not provide any benefit over running it a single time on that agent.
    • engine-criteria-unsatisfied: Indicates that none of the agents could satisfy the engine requirements to start the stub on. This might occur if none of the agents support dedicated stub deployments.
    For example:
    • To ignore a specific set of problems: <force if="reused-agent agent-criteria-unsatisfied"/>
    • To ignore all problems apart from a particular set of problems: <force unless="agent-criteria-unsatisfied"/>
  • Dedicated engine element:

    Use this option to run the stub by using a dedicated engine that is not used to run other stubs even if they are published from the same project. You can specify the JVM options by using the dedicatedEngineJvmOptions parameter and specify the values such as the maximum memory, initial memory, and the garbage collection policy for the engine.

Response body

If the agent element in the request data had a count attribute specified (even if its value is "1"), the response data is of the form:

<?xml version="1.0" encoding="UTF-8"?>
<instances>
	<instance id="id" status="Deploying|Running|Stopping|Error|Setting" agentId="id" href="relative URL to stub instance">
	</instance>
	...
</instances>

Otherwise, if the count attribute (or the agent element) was not specified, then the response data is in the following form:

<?xml version="1.0" encoding="UTF-8"?>
<instance id="id" status="Deploying|Running|Stopping|Error|Setting" agentId="id"
href="relative URL to stub instance">
</instance>
instance
Represents a stub instance that is starting (in the same format as Get a specific stub instance (to determine its state))

Get a specific stub definition configuration

URL Resolve the relative URL retrieved from the configuration element of the Get a specific stub definition response, relative to that resource's URL, as defined by section 5.2.2 of RFC 3986.
Method GET
Returns 200 OK
412 PRECONDITION FAILED: If the stub definition, domain or environment could not be found.

Response body

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <tags>
        <tag name="my tag 1" value="default value" />
        <tag name="my tag 2" value="" /> <!-- Default to empty string -->
        <tag name="my tag 3" /> <!-- Default to null -->
        ...
    </tags>
    <behaviours>
        <behaviour name="behaviour instance name">
            <parameters>
                <parameter name="parameter name" value="default value" />
                ...
            </parameters>
        </behaviour>
        ...
    </behaviours>
    <logging level="DEFAULT|NONE|NORMAL|DEBUG" />
    <response-time distribution="FIXED|UNIFORM|GAUSSIAN" minimum="0" maximum="1000" />
</configuration>

Get a list of all stub instances

URL Resolve the relative URL retrieved from the instances element of the Get a specific stub definition response, relative to that resource's URL, as defined by section 5.2.2 of RFC 3986.
Method GET
Returns 200 OK (but could return an empty list).
412 PRECONDITION FAILED: If the stub definition, domain or environment could not be found.

Response body

<?xml version="1.0" encoding="UTF-8"?>
<instances>
    <instance id="id" status="DEPLOYING|RUNNING|STOPPING|ERROR|SETTING" agentId="id" 
href="relative URL to instance" />
    ...
</instances>
href
URLs point to a stub instance.

You can use the Agents REST API to learn more about the agent that is denoted by the returned agentId. For more information about the REST services for agents, see Agents REST API specification.

Get a specific stub instance (to determine its state)

URL Resolve the relative URL retrieved from the Get a list of all stub instances response, relative to that resource's URL, as defined by section 5.2.2 of RFC 3986.
Method GET
Returns 200 OK
412 PRECONDITION FAILED: If the stub instance, stub definition, domain, or environment could not be found..

Response body

<?xml version="1.0" encoding="UTF-8"?>
<instance id="id" status="DEPLOYING|RUNNING|STOPPING|ERROR|SETTING" agentId="id" 
href="relative URL to self">
</instance>

You can use the Agents REST API to learn more about the agent that is denoted by the returned agentId. For more information about the REST services for agents, see Agents REST API specification.

Stop a stub

URL Resolve the relative URL retrieved from the Get a list of all stub instances response, relative to that resource's URL, as defined by section 5.2.2 of RFC 3986.
Method DELETE
Returns 202 ACCEPTED: Will attempt to stop the stub, or the specified stub instance was not found, or the specified stub definition was not found.
412 PRECONDITION FAILED: If the domain or environment could not be found.
423 LOCKED: If the environment is locked by another user.

Request headers

X-User

If domain-level security is disabled, this setting can be used to specify the user who is starting the scenario.

Authorization
If domain-level security is enabled a security token must be passed as a HTTP Request header. For more information, see REST and Domain level security.

Response body

The instance that is stopping, in same format as Get a specific stub instance (to determine its state).

Stopping a stub that has multiple running instances

When there is more than one running instance of a stub, the DELETE method might not be successful; in that case, do the following steps:
  1. Get the instances of the stub that you want to stop by using GET:
    GET /RTCP/rest/stubs/domain/environment/project_repository/stub_ID/instances/
    . For example, 
    /RTCP/rest/stubs/default/MC303-R90J0439/vapp5232859859349079888/3f244536:15c30d278ab:-7de0/instances/
  2. Construct the relative URL of the stub instance with its href attribute (as retrieved in the GET response). Following is a screen shot that shows a GET response:stub_instance
    For example, 
    /RTCP/rest/stubs/default/MC303-R90J0439/vapp5232859859349079888/3f244536:15c30d278ab:-7de0/instances/9d2b49c9-1177-4619-a012-13d99e99297d
    .
  3. Run the DELETE method with the URL constructed in Step 2.
  4. Repeat Step 1 to Step 3 for all the running instances of the stub.
Feedback