Stubs REST API specification

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

Stub definitions
- Get a list of all stub definitions
Stub definition
- Get a specific stub definition
- Start stub
Stub definition configuration
- Get a specific stub definition configuration
Stub instances
- Get a list of all stub instances
Stub instance
- Get a specific stub instance (to determine its state)
- Stop a stub

Get a list of all stub definitions

URL	`RTCP_BASE_URL`/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/

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 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" 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, just send the following request:

<?xml version="1.0" encoding="UTF-8"?>
<start-stub />

Here is a description of the child elements that you can include:

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 will take their default values.
Agent element:
- Omitting the agent element will automatically select an agent.
- Agents can be specified by either of the following options:
  - An agent host, using the host attribute. The stubs will be 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 specified in the count attribute will determine how many agents the stub will be started on. Only agents that match the attributes specified will be used. If count is omitted, then it defaults to 1. If attributes are omitted then the agents will not be 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 starting a stub.
- forceUnless: Specify a space-separated list of problem identifiers to not ignore when starting 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 a stub. This does not provide any benefit over running a single stub.
- 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 using a dedicated engine that will not be used to run other stubs even if they are published from the same project. You can specify the JVM options 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 will be of the form:

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

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

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

instance: Represents a stub instance being started (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" href="relative URL to instance" />
    ...
</instances>

href: URLs point to a stub instance.

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" href="relative URL to self">
</instance>

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 can be used to specify the user who is starting the scenario.

This element can be used to perform 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.

Response body

The instance being stopped, in same format as Get a specific stub instance (to determine its state).