Note: In this documentation, we refer to both ALMComplete and QAComplete collectively as QAComplete.

QAComplete Test Automation REST API lets you integrate automated testing tools with the Test Management module. To do this, you need to create an agent – an application that runs on test hosts and exchanges data between the testing tool and QAComplete. An example is Test Agent for TestComplete, Selenium, and ReadyAPI.

Test automation REST API versions

The current version of Test Automation REST API is v2.

The previous version, v1, is obsolete. It is no longer supported.

All examples in this guide are for API v2.

Supported automated testing tools

Currently, Test Automation REST API supports integration with the following automated testing tools:

TestComplete and TestExecute by SmartBear
ReadyAPI and SoapUI OS by SmartBear
Selenium WebDriver for JUnit and TestNG unit testing frameworks
Selenium WebDriver for NUnit unit testing framework

The integration might be expanded in the future to support more automated testing tools.

URL structure

The format of Test Automation REST URLs is:

http(s)://{your-server}/rest-api/service/automation/{version}/{resource}

It has the following parts:

http(s)://{your-server}/rest-api/service is the endpoint URL of QAComplete Test Automation REST API. For SaaS clients the server is https://qacomplete.smartbear.com.
automation is the API name.
{version} is the current API version.
{resource} is the path to the resource to access. For example, /hosts/143.

HTTP methods

Test Automation REST API uses the following HTTP methods:

Method	Usage
GET	Get an existing resource.
POST	Create a new resource.
PATCH	Update an existing resource.

Authentication

The Test Automation REST API uses basic authentication with a login and password. The login is the host ID, and the password is the host’s security token. You get these values when you register a test host in QAComplete. The host ID and token let you access information on test runs only for that specific host.

To register a test host, you need a user's login e-mail and password. You use this information only once. The other API calls will use the host ID and security token. This way, you do not need to store the user account information on the host.

To authenticate, include the Authorization header in your request. To create this header:

Create the string login:password.
Encode this string using Base64.
Add Authorization: Basic (with a space after Basic) before the encoded string.

For example, if an agent runs on a test host with the ID 143 and security token d2e1ffd1-3c74-4ccf-738b-10997283e35f, you use this header:

Authorization: Basic MTQzOmQyZTFmZmQxLTNjNzQtNGNjZi03MzhiLTEwOTk3MjgzZTM1Zg==

Some tools and development libraries let you specify just the login and password. They build the Authorization header automatically.

Security permissions

To register test hosts in QAComplete, you need a user account that belongs to a security group that has Read access to Test Hosts. To view or change the group rights in QAComplete, go to > Setup > Security > Security Groups and click to the left of the group.

Other API operations use security tokens and do not depend on user security rights.

JSON and HTTP headers

Most API operations use JSON as the data format. To make a request with a JSON body, use the following header in the request:

Content-Type: application/json

If an operation returns JSON data, also add the Accept header to your request:

Accept: application/json

Date and time

Timestamps are in UTC, in the ISO 8601 format. The format is YYYY-MM-DD, followed by the T letter, then the 24-hour time HH:MM:SS[.sss], then the Z letter.

For example, July 22, 2014 2:30 PM PDT (9:30 PM UTC) is represented as:

2014-07-22T21:30:00Z

Response codes

API calls indicate the result (success or error) using the corresponding HTTP status codes.

HTTP Status Code	Description
200	Request completed successfully. The response depends on the request method used.
302	The requested resource is at a different URL. The client should send a new GET request to that URL. This code is returned by the GET ../script operation if the automation script is specified by a URL.
303	In a response to a POST request, it means that the resource is at a different URL. The client should send a new GET request to that URL.
400	The request cannot be fulfilled due to bad syntax. For example, it might be missing some required data.
401	The request is missing the Authorization header, or the authentication information is invalid.
403	The authenticating user does not have the rights to perform the operation.
404	The requested resource does not exist.
408	The server timed out waiting for the request. The client may repeat the request later.
500	Internal server error. Some possible causes of the error: A wrong HTTP method is used (for example, PUT instead of POST) The client is trying to add a resource that already exists

The response body may have additional error information in the JSON object, for example:

{
  "errors": [
    {
      "message": "Host with id 15 not found",
      "code": 404
    }
  ]
}

Examples

This guide includes two types of examples:

Raw HTTP requests and responses.
Requests made by using the command-line tool cURL. cURL is preinstalled on Mac OS X and on many Linux systems. Windows users can download cURL from http://curl.haxx.se/download.html.

API web interface

The API has a web interface where you can see the available API operations and parameters, make API calls and view the returned data. You can access the API web interface at this URL:

http://{server}/rest-api/swagger/index.html

The first time you make an API call, you will be asked to enter the QAComplete email and password for authentication.

The web interface accesses and changes real live data, please be careful.

QAComplete Test Automation REST API Overview