Rational Test Control Panel Stubs REST API Reference

Forward compatibility

Important: To improve forward compatibility of clients of the REST API, no manual construction of URLs should be performed, except for the construction of the Query URL.

URLs should be generated by resolving the relative hrefs provided in the XML. These should be resolved against the URL that they were returned from.

Query URL

URL:
- <RTCP_BASE_URL>/rest/stubs/
Query parameters:
- domain (Required): The name of the domain.
- env (Required): The name of the environment.
- stub (Optional): The name of the stub, do not specify this parameter if id parameter is specified.
- id (Optional): The id of the stub, do not specify this parameter if stub parameter is specified.
- comp (Optional): The name of the lowest-level containing component for the stub.
- op (Optional): The name of the containing operation for the stub.
- version (Optional): The version of the stub.
Examples:
- <RTCP_BASE_URL>/rest/stubs/?domain=default&env=testEnv&comp=My%20component&op=My%20operation&stub=My%20stub&version=1.0
- <RTCP_BASE_URL>/rest/stubs/?domain=default&env=testEnv&stub=My%20stub

Response data:

<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 stub definitions.

Response codes:
- 200 OK (But may 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.
If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

Resources

Stub definition

URL:
- Resolve the relative URL retrieved from the query URL response, relative to <RTCP_BASE_URL>/rest/stubs/, as defined by section 5.2.2 of RFC 3986.
- Normally this is in the form of <RTCP_BASE_URL>/rest/stubs/[relative URL from query response], but this should not be relied upon.

`GET` request

Response data:

<stub>
    <configuration href="relative URL to stub definition configuration" />
    <instances href="relative URL to stub instances list" />
</stub>

Response codes:
- 200 OK
- 412 PRECONDITION FAILED: if the stub definition, domain or environment could not be found
If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

`POST` request on stub definition: Start stub

Request headers:
- X-User: may be used to specify the user who is starting the stub.
  - This will allow the operation to be performed through an already-obtained environment lock.
  - For more information about environment locks, see the Rational Test Virtualization Server Reference Guide and the Rational Test Control Panel Environment Locking REST API Reference.
- Content-Type: application/xml
Request data:
- ```
<start-stub>
    <configuration>
        ...
    </configuration>
    <agents>
        <agent host="host name or IP (as specified by agent)">
            <attributes>
                <attribute value="attribute name" />
                ...
            </attributes>
        </agent>
    </agents>
</start-stub>
```
  To start the stub on a default agent with default configuration, just send:
```
<start-stub />
```
  - configuration element is as defined in Stub definition configuration, but with the actual values to use.
    - configuration child elements are optional, and if omitted will take their default values.
  - Omitting the agent element will automatically select an agent.
  - Either an agent host or agent attribute(s) can be specified.
  - Agent attributes (the value of the value attribute of the attribute elements) must not contain commas, and are case-insensitive.
  - Only 1 agent can be specified.
Response data:
- Stub instance being started (in same format as GET stub instance).
Response codes:
- 200 OK: Will attempt to start the stub.
- 400 BAD REQUEST: If the request data could not be understood.
- 412 PRECONDITION FAILED: If the stub definition, domain or environment could not be found, or if there are no agents available (or if the stub was cancelled straight away, although this is unlikely to happen).
- 500 INTERNAL SERVER ERROR: If anything else went wrong, including resources not found.
If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

Stub definition configuration

URL:
- Resolve the relative URL retrieved from the configuration element of the stub definition resource response, relative to that resource's URL, as defined by section 5.2.2 of RFC 3986.
- Normally this is in the form of <RTCP_BASE_URL>/rest/stubs/[relative URL from query response]/[relative URL from stub definition resource], but this should not be relied upon.

`GET` request

Response data:

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

Response codes:
- 200 OK
- 412 PRECONDITION FAILED: if the stub definition, domain or environment could not be found.
If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

Collection of stub instances

URL:
- Resolve the relative URL retrieved from the instances element of the stub definition resource response, relative to that resource's URL, as defined by section 5.2.2 of RFC 3986.
- Normally this is in the form of <RTCP_BASE_URL>/rest/stubs/[relative URL from query response]/[relative URL from stub definition resource], but this should not be relied upon.

`GET` request

Response data:

<instances>
    <instance id="id" status="DEPLOYING|RUNNING|STOPPING|ERROR|SETTING" href="relative URL to instance" />
    ...
</instances>

href URLs point to stub instances.
The status value strings must be checked case-insensitively.

Response codes:
- 200 OK (But may return an empty list).
- 412 PRECONDITION FAILED: if the stub definition, domain or environment could not be found.
If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

Stub instance

URL:
- Resolve the relative URL retrieved from the collection of stub instances resource response, relative to that resource's URL, as defined by section 5.2.2 of RFC 3986.
- Normally this is in the form of <RTCP_BASE_URL>/rest/stubs/[relative URL from query response]/[relative URL from stub definition resource]/[relative URL from collection of stub instances], but this should not be relied upon.

`GET` request on stub instance: Retrieve the current status of the stub instance.

Response data:

<instance id="id" status="Deploying|Running|Stopping|Error|Setting" href="relative URL to self">
</instance>

For forward-compatibility, the status value strings should be checked case-insensitively.

Response codes:
- 200 OK
- 412 PRECONDITION FAILED: if the stub instance, stub definition, domain or environment could not be found.
If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

`DELETE` request on stub instance: Stop stub.

Request headers:
- X-User: may be used to specify the user who is starting the stub.
  - This will allow the operation to be performed through an already-obtained environment lock.
  - For more information about environment locks, see the Rational Test Virtualization Server Reference Guide and the Rational Test Control Panel Environment Locking REST API Reference.
Response data:
- Instance being stopped (in same format as GET stub instance).
Response codes:
- 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.
If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

Rational Test Control Panel Stubs REST API Reference

Forward compatibility

Query URL

Resources

Stub definition

GET request

POST request on stub definition: Start stub

Stub definition configuration

GET request

Collection of stub instances

GET request

Stub instance

GET request on stub instance: Retrieve the current status of the stub instance.

DELETE request on stub instance: Stop stub.

`GET` request

`POST` request on stub definition: Start stub

`GET` request

`GET` request

`GET` request on stub instance: Retrieve the current status of the stub instance.

`DELETE` request on stub instance: Stop stub.