XTC 76 shipped with the first part of an API to get access to selected XTC resources and trigger selected operations from automated environments. This part provides remote access to load tests. This includes
- listing and inspecting load tests,
- duplicating and executing load tests, and
- downloading result and report archives.
Please note that this feature is still in beta. We encourage you to test it, but be prepared for changes, even incompatible ones, in the next releases of XTC.
Managing API Client Credentials
To allow remote access to your load tests, you must first create client credentials. You can do this in your organization or in your projects.
To create client credentials in your organization, go to Configuration > Integrations > API Client Credentials and click the Add button. You will need to specify a name and an optional expiration date. You will also need to select an API version and the scopes (purposes) for which these credentials will be used. API credentials with an expiration date will expire at the end of the specified day (UTC).
Submit the dialog and XTC will show you the generated client secret, which you can now copy to a safe place. You will not be able to access it again, so if you lose or forget the secret, fresh credentials have to be created.
Note that client credentials cannot be modified. If you want to change them, delete them and recreate them as needed.
The client credentials defined in your organization are valid for accessing resources in your organization and, by default, in all of your projects. However, org credentials can be disabled in your project(s). Go to Configuration > Integrations > API Client Credentials in a project and disable the org client credentials for that project if necessary.
In the same location, you can also create project-level API client credentials, similar to the org-level credentials as described above. These credentials will only allow access to the resources of that project.
Whether you use org-level or project-level credentials, or a mix of both, depends on your security requirements.
Obtaining an Access Token
To actually use the API, you need an access token. To get one in an automated way, use the tool of your choice, but we will demonstrate this using
curl -X POST \
-d "client_id=<your-client-id>" \
-d "client_secret=<your-client-secret>" \
-d "grant_type=client_credentials" \
-d "scope=LOADTEST_LIST LOADTEST_STATUS LOADTEST_DETAILS LOADTEST_COPY_RUN LOADTEST_REPORT_DOWNLOAD LOADTEST_RESULT_DOWNLOAD" \
As you can see, you need to pass both the client ID and secret, but also the grant type
client_credentials and the scopes for which this token will be used. The scope list may contain fewer scopes than defined in the credentials, but no more.
Now run the curl command. XTC will return a JSON response. Look for the
access_token field. Note that this access token expires automatically after one hour, but you can create new tokens at any time.
Making API Calls
Now we are ready to make our first API call: listing all the load tests in a project. Don’t forget to provide the access token and the short names of your organization and project (you can find these in the org’s or project’s configuration):
curl -X GET \
-H "Authorization: Bearer <your-jwt-access-token>" \
If all went well, you should see a JSON response with all your load tests printed to the console.
For your convenience, here is a list of current API endpoints and what they are used for:
Project API Endpoints
- Retrieve the details of a project:
GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>(requires scope
- List all the projects of an organization:
GET /public/api/v1/orgs/<org-short-name>/projects(requires scope
Load Test API Endpoints
- Copy the specified load test and run the copy:
GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>/runCopy(requires scope
- List the details of a certain load test:
GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>(requires scope
- List all load tests in a project:
GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests(requires scope
- Download the specified report archive:
GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>/reports/<report-number>/download(requires scope
- Download the specified result archive:
GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>/results/<result-number>/download(requires scope
- List the status of a certain load test:
GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>/status(requires scope
API Documentation and Explorer
For a complete formal documentation, visit https://xtc.xceptance.com/public/api/json or https://xtc.xceptance.com/public/api/yaml. There you will find the OpenAPI-compliant specification of all existing API endpoints, including their respective request and response types, in either JSON or YAML format.
In addition to the OpenApi specification in JSON or YAML format, XTC also presents the definition of its public APIs as a browsable documentation, the XTC API Explorer: this includes the help texts as well as the input and output data types for each API endpoint.
You can also try API calls directly from the API Explorer. For this to work, you will need to configure authorization information. To do this, go to Authentication in the menu. You can then provide either a valid bearer access token or specify client ID and secret as well as the required scopes for XTC to create a new bearer access token on your behalf using the OAuth procedure.
Handling authentication in the API explorer: an access token has been created for the entered client ID and secret.