Rational Test Control Panel Environment Locking API Reference

Forward compatibility

Query URL

• URL:
  • <RTCP_BASE_URL>/rest/environments/

GET request

• Query parameters:
  • domain: The name of the domain (required).
  • env: The name of the environment (required).
• Example:
  • <RTCP_BASE_URL>/rest/environments/?domain=default&env=test
• Response data:

  <environments>
      <environment name="name" href="relative URL" />
  </environments>

  • href URLs point to environments, relative to <RTCP_BASE_URL>/rest/environments/.
• 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 could not be found. (If the environment could not be found, a 200 OK status code is returned with an empty environments element. This is different to the stubs and scenarios APIs, as in this case it is the environments that are being queried for, rather than looking for other resources inside an environment.)

  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

Environment

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

GET request

• Response data:

  <environment name="name">
      <lock locked="true|false" href="relative URL" />
  </environment>

  • The locked attribute indicates whether the environment is currently locked (true) or unlocked (false).
  • href URLs point to environment locks. These URLs are present even if the environment is not locked, even though a GET request on them would result in 404 NOT FOUND; they are needed for the POST request used to obtain a lock.
• Response codes:
  • 200 OK
  • 404 NOT FOUND: If the environment could not be found.
  • 412 PRECONDITION FAILED: If the domain 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.

Environment lock

• URL:
  • Resolve the relative URL retrieved from the environment resource GET 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/environments/[relative URL from query response]/[relative URL from environment resource], but this should not be relied upon.

GET request on environment lock: Retrieve information on the existing lock, if any.

• Response data:

  <lock>
      <user name="username" />
      <time start="start timestamp in milliseconds" expected-duration="expected duration in milliseconds" />
      <reason>reason</reason>
  </lock>

  • The start and expected-duration attributes are 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 if their values have not been set.
• Response codes:
  • 200 OK: A representation of the lock has been returned. The environment may or may not be locked (see note for 404).
  • 404 NOT FOUND: If the environment is not locked. Note: do not rely on this status code to determine if an environment is locked. Use the <lock locked="true|false" ... /> attribute on the environment resource as the definitive state of the lock. Future versions of the API may return 200 OK and a representation of an empty lock as the response to this GET request when the environment is not locked.
  • 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.

POST request on environment lock: Create an exclusive lock on an environment.

• Request headers:
  • X-User: A URL-encoded username to identify the user who is to own the lock (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.
  • Content-Type: application/xml
• Request data:

  <lock>
      <time expected-duration="expected duration in milliseconds" />
      <reason>reason</reason>
  </lock>

  • This is the same as the GET environment lock 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.
• Response codes:
  • 201 CREATED: If the environment was successfully locked.
  • 400 BAD REQUEST: If the request data could not be understood.
  • 409 CONFLICT: If another user already has the lock.
  • 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.

DELETE request on environment lock: Release the lock.

This can only be performed if the specified user either owns the lock or is an administrator.

• 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.
• Response codes:
  • 200 OK
  • 403 FORBIDDEN: If the specified user is not the one who holds the lock, and is not an admin.
  • 404 NOT FOUND: If there was no lock to release.
  • 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.