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:
-
Create the string
login:password.The login is your user name in QAComplete and the password is your password in QAComplete.
-
Encode this string using Base64.
-
Add "Authorization: Basic " (with a space after Basic) before the encoded string.
For example, if your login is [email protected] and the security token is d2e1ffd1-3c74-4ccf-738b-10997283e35f, you use the following header:
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:
|
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:
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.