Rational Test Control Panel Stubs REST API Reference

Forward compatibility

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)
  • 412 PRECONDITION FAILED: If the domain was not found

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 could not be found

POST request on stub definition: Start stub

• Request headers:
  • 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.
    • 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 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.

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 could not be found.

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.
  • For forward compatibility, the status value strings should be checked case-insensitively.
• Response codes:
  • 200 OK (But may return an empty list).
  • 412 PRECONDITION FAILED: if the stub definition could not be found.

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 could not be found.

DELETE request on stub instance: Stop stub.

• Response data:
  • Instance being stopped (in same format as GET stub instance).
• Response codes:
  • 202 ACCEPTED: Will attempt to stop the stub.