Applies to QAComplete 12.31 SaaS & On-Premises, last modified on September 12, 2019

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

You use QAComplete REST API to access and manage items of various types in QAComplete from external applications.

This REST API is available since QAComplete version 10.2.

Current version

Currently, the REST API of QAComplete supports both the v1 and v2 operations. To learn which version a specific operation uses, see the article describing the needed operation.

URL structure

The REST API of QAComplete uses URLs of the following format:

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

It has the following parts:

Part Description
http(s)://{your-server}/rest-api/service/api The endpoint URL of QAComplete REST API.
For SaaS clients, the your-server is always https://rest.qacomplete.smartbear.com/rest-api/service.
{version} The current API version.
{resource} The path to the resource to access. For example, /defects/17.

HTTP methods

QAComplete REST API uses the following HTTP methods:

Method Usage
GET Gets an existing resource.
POST Creates a new resource.
PUT Updates an existing resource. Use it to update the entire resource contents.
PATCH Updates an existing resource. Use it to update the needed properties of the resource.
DELETE Deletes the specified resource.

Authentication

To call any QAComplete API operation, authentication is needed. To log in to QAComplete, you send your user name (login) and password to QAComplete in your first request (see below). QAComplete will respond with a security token. In your subsequent requests, you will need to specify your login and the security token.

Currently, it is impossible to access the QAComplete REST API using the single sign-on credentials.

QAComplete uses basic authentication with a login and password (you can find more information on it in the MSDN library).

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

  1. Create the string login:password.

    The login is your user name in QAComplete and the password is your password in QAComplete.

  2. Encode this string using Base64.

  3. Add "Authorization: Basic " (with a space after Basic) before the encoded string.

For example, if your login is John.Smith@edgb.com and the security token is d2e1ffd1-3c74-4ccf-738b-10997283e35f, you use the following header:

Authorization: Basic MTQzOmQyZTFmZmQxLTNjNzQtNGNjZi03MzhiLTEwOTk3MjgzZTM1Zg==

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

Security permissions

QAComplete provides various levels of security permissions (Read, Add, Update, and Delete) that allow access to specific project areas (defects, requirements, and so on). Security rights are assigned to user groups, not to individual users.

To use the API, a user must have access to the target project and a sufficient access level for the needed project area.

To check if a user can access a project
  • In QAComplete, go to  > Setup > Security > Users.

  • Click to the left of any user.

  • Select Show all projects (not just my projects).

The user’s access levels appear in the Security Group column.

To view or change security rights for a user group
  • In QAComplete, go to  > Setup > Security > Security Groups.

  • Click to the left of any group.

  • In the Security Group combo box, select the user’s group.

  • Review or change the security rights for that group.

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[.sssssss]).

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

2014-07-22T21:30:0000000

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.
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 An 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": "Entity Bugs with Id 143 wasn't 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 this web site:

    http://curl.haxx.se/download.html

You can find sample requests and responses in the topics describing the operations.

For examples of requests that perform typical actions, see the topics of the How To section.

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://{your-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.

You can also see descriptions of QAComplete REST API on the following pages:

  • http://{your-server}/rest-api/service/resources – Describes resources that QAComplete REST API implements.

  • http://{your-server}/rest-api/service/resource/api – Describes operations that you can call to work with QAComplete data, their parameters and results.

See Also

QAComplete REST API Reference
How To

Highlight search results