Environments 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 Look up a URL for an environment 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

Look up a URL for an environment

Response body

<?xml version="1.0" encoding="UTF-8"?>
<environments>
    <environment name="name" href="relative URL" />
</environments>

href

URLs point to an environment, relative to RTCP_BASE_URL/rest/environments/

Get a specific environment

Response body

<?xml version="1.0" encoding="UTF-8"?>
<environment
      name="name"
      description="environment description">
    <lock locked="true|false" href="relative URL" />
    <base-environment name="name of base environment" href="relative URL to base environment"/>
    <tags>
        <tag name="tag name" value="tag value" />
        <tag name="tag name 2" value="tag value 2" />
    </tags>
</environment>

name

The name of the environment.

description

The description of the environment.

base-environment

Identifies the environment that is the "base" environment of this environment. This element's href attribute contains a relative URL to the base environment's resource.

tags

The environment tags set on this environment. This will not include any environment tags from published Rational Integration Tester projects, only those that have been set on IBM Rational Test Control Panel itself. The tags element will be omitted if there are no tags saved.

lock

Provides details of the lock.

locked

Indicates whether the environment is currently locked (true) or unlocked (false).

href

Points to an environment lock. This URL is present even if the environment is not locked, even though a request on it to Retrieve information on the existing lock, if any. would result in 404 NOT FOUND; it is needed for the POST request used to obtain a lock.

Update the environment tags

Request headers

X-User

If the domain security is disabled, use this header to specify the user who is performing the operation. This will allow the operation to be performed through an already-obtained environment lock. For more information on environment locks, see environment lock.

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

• The same format as returned from Get a specific environment, constructed as follows:
  • Construct this data from a GET request performed immediately prior to this PUT request. The tags element may be added before resubmission if it was not present in the GET request response.
  • All elements and attributes returned from that GET request MUST be included in the PUT, unless intended to be deleted by this request.
  • Only changes to the tags element and its children are supported. All other values MUST be submitted unchanged (however, the server may ignore such invalid changes without returning an error status but this behaviour must not be relied on).

Delete an environment

Request headers

X-User

Used to specify the user who is performing the operation. This element is used to perform the operation through an already-obtained environment lock. For more information on environment locks, see environment lock.

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.

Retrieve information on the existing lock, if any.

Response body

<?xml version="1.0" encoding="UTF-8"?>
<lock>
    <user name="username" />
    <time start="start timestamp in milliseconds" expected-duration="expected duration in milliseconds" />
    <reason>reason</reason>
</lock>

name

The name of the user who acquired the lock.

start and expected-duration

measured in milliseconds in the same manner as the java.lang.System.currentTimeMillis() Java™ API method call.

reason

Text, specified in character data, either in plain entity-encoded text, or in a CDATA block. Newlines should be respected. There is no guarantee that blocks of whitespace will not be collapsed.

Create an exclusive lock on an environment.

Request headers

X-User

Used to specify the user who is performing the operation (no password required). This must also be used on all other calls to any REST endpoint that modifies the environment while the environment lock is in place.

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"?>
<lock>
    <time expected-duration="expected duration in milliseconds" />
    <reason>reason</reason>
</lock>

• This is the same as the Retrieve information on the existing lock, if any. response but the user element and start attribute are ignored.
• The expected-duration attribute is measured in milliseconds in the same manner as the java.lang.System.currentTimeMillis() Java API method call.
• The reason text is specified in character data - either in plain entity-encoded text, or in a CDATA block. Newlines should be respected. There is no guarantee that blocks of whitespace will not be collapsed.
• The expected-duration attribute or the reason element may be omitted.

Release an environment lock

Request headers

X-User

A URL-encoded username to identify the user performing the unlock request (no password required). The user must match the user who created the lock. This can only be performed if the specified user either owns the lock or is an administrator.

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.