REST services

Representational state transfer (REST) is a simple stateless architecture that generally runs over HTTP. When used in conjunction with HCL DevOps Test Virtualization Control Panel (Test Virtualization Control Panel), HTTP methods (such as GET and POST) are mapped to actions on domains, environments, scenarios, stubs and other resource types.

Overview

From version 9.2.1 onwards, all REST services are accessible from the base URL of /RTCP/api/ and are defined by using Swagger. A navigable user interface lists the available set of APIs at /RTCP/api/swagger-ui.html. This Swagger file describes the individual APIs along with details of the parameters and response bodies.

The Swagger definition can be downloaded by noting the partial URL at the top of the swagger-ui.html page and appending this to the base API URL. For example /RTCP/api/v2/api-docs. This allows you to synchronize in HCL DevOps Test Integrations and APIs (Test Integrations and APIs) and access the services through tests.

To see how these REST APIs relate to the other APIs that are available, see Working in non-GUI mode.

REST response codes and error messages

If the response code is 400 or greater, and the Content-Type is text/plain, the response body contains a plain-text error message.

REST and Test Virtualization Control Panel security

If security is enabled, a security token must be passed as an HTTP Request header.

Authorization: X-Jazz-Session token

where token is the string representing the security token. For information about how to create a security token, see Creating and assigning security tokens.

If domain-level security is enabled, you can use the long-term token created for you by the Test Virtualization Control Panel system administrator. Your username must have been granted API User role for the domain that contains the REST services that you want to use.

You can also use the following method to create a temporary session token based on your username and password.

Get a list of URLs to use for authentication

Construct the authorization API URL by adding auth/discovery to the Test Virtualization Control Panel base URL, as in the following example:
```
https://example.com:5443/RTCP/auth/discovery
```

Send an HTTP GET request to the authorization API URL. The URL returns a message in JSON format that specifies additional URLs, as in the following example:

{
  "subject": "https://example.com:5443/RTCP/auth",
  "links": [
    {
      "href": "https://example.com:5443/RTCP/auth/token",
      "rel": "http://jazz.net/auth/jsa/token"
    },
    {
      "href": "https://example.com:5443/RTCP/auth/introspection",
      "rel": "http://jazz.net/auth/jsa/introspection"
    },
    {
      "href": "https://example.com:5443/RTCP/auth/session-sign-in",
      "rel": "http://jazz.net/auth/jsa/session-signin"
    },
    {
      "href": "https://example.com:5443/RTCP/auth/session-sign-out",
      "rel": "http://jazz.net/auth/jsa/deauthorize"
    }
  ]
}

Sign in and create a session

In the response from the authorization URL, locate the rel property with the following value:
```
http://jazz.net/auth/jsa/session-signin
```
See Get a list of URLs to use for authentication.
Send a POST request to the URL in the associated href property. That POST request uses HTTP Basic Authentication and specifies the username and password for the appropriate user account.
Using HTTP Basic Authentication involves setting the Authorization HTTP request header to the string "Basic" followed by a space, followed by a base64-encoded string that consists of the username, a colon, and the password. For example, for the username "user1" and the password "password", construct the string "user1:password". After base64 encoding, the string becomes "dXNlcjE6cGFzc3dvcmQ=". The following example shows the HTTP request:
```
POST /RTCP/auth/session-sign-in HTTP/1.1
Host: example.com:5443
Authorization: Basic dXNlcjE6cGFzc3dvcmQ=
Content-Length: 0
```
That request returns a response similar to the following example:
```
{ "token_type" : "urn:jazz:params:oauth:token-type:session",
  "access_token" : "552359hakks86205mqjdgy",
  "jazz_subject" : "user1"}
```
The jazz_subject property contains the username that you created a session for. The access_token property contains the security token for this session. For information about how to use this token to run REST API calls as this user, see REST and Test Virtualization Control Panel security.
In subsequent requests to other REST endpoints in the same domain, include that access token in the Authorization header and use the "X-Jazz-Session" as the authentication scheme identifier, as in the following example:
```
Authorization: X-Jazz-Session 552359hakks86205mqjdgy
```

Session logout

When using temporary session access, use the logoutUsingDELETE operation to close the session.

Pass the Authorization header as detailed in REST and Test Virtualization Control Panel security.

You do not need to close the session when you use the domain-level security long-term token.