REST services
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
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:
See Get a list of URLs to use for authentication.http://jazz.net/auth/jsa/session-signin
- 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