REST services

Representational state transfer (REST) is a simple stateless architecture that generally runs over HTTP. When used in conjunction with IBM® Rational® Test 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, 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 Rational Integration Tester 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 Domain level security

Note: Domain-level security is supported in Rational Test Control Panel 8.5.1.1 or later. By default, domain-level security is not enabled.

If domain-level security is enabled a security token must be passed as a HTTP Request header.

Authorization: X-Jazz-Session token

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

To include an authentication token in a REST call, use the following procedure.

Get a list of URLs to use for authentication

Construct the authorization API URL by adding auth/discovery to the Rational Test 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 Domain level 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
```

Feedback