Swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

As of version 4.8 Enterprise Tester now supports describing its API in a swagger compatible manner.

Retrieving the Swagger JSON

Swagger describes the various resources, methods and parameters of a REST API in JSON format. The swagger specification is documented here.

In Enterprise Tester the Swagger API List resource allows retrieval of the “swagger JSON” for the Enterprise Tester API.

Interacting with the API via Swagger UI

Swagger includes its own viewer called Swagger UI – which uses the Swagger JSON output to generate interactive documentation for Swagger-documented API, allowing you to easily try various API methods without requiring a client or programming skills.

Enterprise Tester includes a copy of Swagger UI with itself, you can access the client via the link:

http://{et_server_url}/content/vendor/swagger/index.html#!/api

Generating clients

There are a number of client generators for swagger – check out the Swagger website for more details.

Popular client generators such as Swagger codegen and JavaScript client Swagger-client which provide support for generating clients from Enterprise Tester’s swagger JSON in languages such as Javascript, Ruby, Scala, Java, PHP and Python.

OData (Open Data Protocol)

Some parts of the REST API expose collections which can be queried via OData mechanisms.

ODATA, or Open Data Protocol, is an involved standard allowing for adhoc filtering, paging (and much more) of resources – more details can be found here.

Currently Enterprise Tester leverages some features of OData as below:

• $filter – Is supported for OData implementing collections.
• $orderby – Is supported for OData implementing collections.
• $expand – Is supported for most resource types, but it’s implementation differs in some ways (we align more closely with the Jira REST API expand functionality).
• $top – Is supported for OData implementing collections (also supported on any collections that take TQL queries).
• $skip – Is supported for OData implementing collections (also supported on any collections that take TQL queries).

Enterprise Tester at current does not intend to be OData compliant, in particular we have no plans to implement the navigation or metadata features that are within OData, at least not for the first version of the API.

Please see the Uri Conventions topic on the OData website for more information on how the various query parameters can be used to compose queries.

URL structure

Just to whet your appetite, here is a simple query of the projects collection – demonstrating projects being filtered, ordered and paged:

GET /api/projects?$filter=substringof('test',Name) eq true&$orderby=Name desc&$top=5

Pulling the URL apart we can see that:

• The filter is “substringof(‘test’,Name) eq true” – this will find all projects containing the word ‘test’ ($filter = substringof(‘test’,Name))
• we are sorting by the Name of the project, in descending order. ($order=Name desc)
• We want the first 5 resuts only ($top=5)

Examples

Example – Query without inline count

Url:

 http://myserver/EnterpriseTester/api/users?$filter=Name eq 'john'&$top=2

Results:

Example – Query with inline count

Url:

http://myserver/EnterpriseTester/api/users?$inlinecount=allpages&$top=2&$skip=3

Results:

JSONP

JSON (Json with Padding) complements in the existing capability of Enterprise Tester API methods to return JSON. It provides a method to request data from the server where CORS is not a viable alternative.

In a JSONP request, the contents of the response is wrapped in a javascript function call, which allows you to fetch it with a script tag, and the have to response automatically invoke the callback once loaded, to process the response body – let’s take a look at an example:

To make a JSONP request you pass an additional query parameter as part of the url with the name “callback”, the value of which is the name of the callback function to invoke:

Example

If we make a request as follows:

GET http://localhost/EnterpriseTester/api/groups?callback=processResponse

Then we can see in the response, that it’s wrapped in a call to the function processResponse:

Limitations

JSONP requests are only support for GET HTTP methods.

Expand

Overview

The Enterprise Tester REST API makes extensive use of a feature called Expand (also known as Expansions) – resources that support expanding will return the list of available expansions in a property of the representation, called “Expand” – here is an example of a “project” resource with a set of available expand values:

When making a request, you can include a query parameter called $expand that provides a comma separated list of expands you wish to have expanded in the response – so for example, to get the priority and status picklists back with the project, you would use a request like this:

GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=Status,Priority

In the response those properties will be expanded, and will no longer be listed in the “Expands” property as available properties to expand.

Expansions can be more than one level deep. Here is an example of getting a project, with its top level requirement package expanded, and each of those packages children collection expanded as well.

We do this by using a period (.) to navigate to the child expansion:

GET /api/project/593c2fb5-2300-4bce-ad50-9f07009b207c?$expand=RequirementPackages.Children

As you can see the child packages are then expanded as well:

For each method supported by a resource (GET, POST, PUT) documented within the help system, we also include details of the available expansions.

Deep Expansion

You are not limited to expanding to one or two levels – to expand many levels of depth, you can continue to use a period character between each level i.e. RequirementPackages.Children. Children will return the requirement package, with its children and those children’s children.

GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=RequirementPackages.Children.Children

As we can see the multiple levels are expanded as requested:

‘All’ Expansion

When exploring the API it can be useful to expand everything, so you can see what information is available – this can be done through the pseudo-expansion “All” i.e.

GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=All

This will automatically be replaced with all available expands in the response:

You can use multiple levels of “All” as well – but we strongly advise against using “All” when writing code that interacts with the API as it will cause very large payloads to be returned and negatively impact on the performance of Enterprise Tester.

CORS (Cross-origin Resource Sharing)

CORS (Cross-origin resource sharing) is a web browser specification that defines a way for a web browser and web client to interact in such a way that cross-origin (requests to a server in a different domain) are allowed, for all HTTP methods.

Support for CORS in Enterprise Tester was introduced in version 4.4 and above, and currently supports:

• CORS without authentication (will use session authentication however, if user is already authenticated with the Enterprise Tester server in the same browser session).
• CORS with authentication (Enterprise Tester will handle both pre-flighted and immediate requests, by returning the “Access-Control-Allow-Credentials” header – allowing the use of Basic Authentication).

Because a web browser and it’s scripts are inherently insecure to the operator (the user operating the browser can see the javascript/html in raw form easily) – when using CORS with Basic Auth we strongly advise against storing the ET login and password credentials in javascript, and instead they should be retrieved from the user interactively and not stored.

And as always, when using basic Auth, we recommend you access Enterprise Tester via HTTPS (SSL).

Examples of using CORS with Enterprise Tester can be found in the CORS Examples section of our API Github Repository.

Consistency

By default API methods that change data in Enterprise Tester will attempt to wait until those changes have also been reflected in the indexes (such as the Run or Entity index).

If you are performing bulk insert operations, and do not rely on needing to be able to immediately query via TQL and retrieve acurate results based on the the data that was created, updated or deleted then you can choose to “opt out” of this wait mechanism.

To do so you request must either:

• Include the query parameter “wait-until-indexed” with the value “false”.
• Include the request header “wait-until-indexed” with the value “false”.

If the query parameter or header is not present, or set to true, then the default behavior of waiting until the entity is indexed after persisting any changes will apply.

Bulk Actions

Overview

Bulk actions are a common extension point within Enterprise Tester, exposed as features of the grid (normally a button, or selection field and button combination).

Bulk actions can be invoked asynchronously by issuing a POST request to the backgroundtasks collection resource, with the configuration information including the command being invoked passed in the Parameters collection, as show in the example below:

If we pull apart the above request we can see that we are:

• Invoking the command “BulkCopy”.
• Invoking the command scenario “BulkCopyScriptsScenario” – many commands have more then one associated scenario, and you must use the scenario applicable to your source and target package type, and the type of items you have selected.
• For move and copy operations there needs to be a target and source package (targetPackageId and sourcePackageId) – the source package is used as the “Root” of the bulk copy/move operation so that retain structure can calculate what folders are required.
• In the above example, our targetType and targetId is the same as the targetPackage.
• The selected items to copy “selections” – each selection features an Id and a Type (any type which is supported in TQL as a valid EntityType alias will work here i.e. Script and TestScript will both be treated as a TestScript entity type).
• “retainStructure” – which is a parameter specific to bulk/copy move to retain the packages related to the sourcePackage when copying to the targetPackage.

Available commands

• Bulk Assign (AssignBulkActionScenario)
• Bulk Copy (BulkCopyAssignmentsScenario, BulkCopyRequirementsScenario, BulkCopyScriptsScenario)
• Bulk Create Assignments (BulkCreateScriptAssignmentsScenario)
• Bulk Create Scripts (BulkCreateScriptsScenario)
• Bulk Create Scripts From Agile Runs (BulkCreateScriptsFromAgileRunsScenario)
• Bulk Delete (BulkDelete)
• Bulk Move (BulkMoveAssignmentsScenario, BulkMoveRequirementsScenario, BulkMoveScriptsScenario)
• Export (CSV)
• Traceability (CSV)
• Update Script Statuses (UpdateScriptStatusBulkActionScenario)

CSV Export command

The CSV Export command is an example of an action which has a payload (an exported file) which you can download after completing the action – first, here is an example of a CSV export task being created:

As a result of creating this task, the response will indicate where the task updates can be fetched from via GET using the “Self” URL:

When the task has completed, fetching the task will include in it’s response details of the where you can then download the exported file from (indicated in the “exportedfile” link).

Authentication

Enterprise Tester allows you to authenticate to the REST API via three methods:

• Session – this allows javascript running within the Enterprise Tester application to access the API as the currently logged in user.
• Basic – passing the login/password as a header with each request – if security is a concern, this should not be used unless Enterprise Tester is accessed via HTTPS (SSL).
• OAuth 1.0 – users can authenticate with Enterprise Tester via OAuth and then make requests using the returned access token.

Most users will want to use Basic Auth due to its simplicity, unless building a 3rd party add-on for Enterprise Tester. In this case we recommend the use of OAuth, so your application is not required to store user logins and passwords.

Basic Auth

Basic Auth combined with SSL will often suffice as the authentication mechanism for interacting with the Enterprise Tester API, here is an example of using Curl to retrieve a list of projects from Enterprise Tester with basic auth:

curl -u Administrator:password http://localhost/EnterpriseTester/api/project/650d8904-c145-4f7c-8b65-a02a0092a85f

In this case we are retrieving the project with ID “650d8904-c145-4f7c-8b65-a02a0092a85f” with the login “Administrator” and the password “password”.

OAuth 1.0

Enterprise Tester supports OAuth 1.0a.

Implementing an OAuth 1.0a client is outside the scope of this help topic, but the key things required to establish the connection are:

Get Request Token Url

http://localhost/EnterpriseTester/OAuth/Token/GetRequestToken.rails

This is Url that you can retrieve the request token from.

User Authorization Url

http://localhost/EnterpriseTester/OAuth/Authorization/PromptForAuthorization.rails

This is the Url that you send users to, so they can authorize the request for access.

Get AccessToken Url

http://localhost/EnterpriseTester/OAuth/Token/GetAccessToken.rails

This is the Url used to exchange the request token for the access token that you can use to sign all your API requests.

For more information on the mechanics of signing a request with your access token, we recommend that you read through a tutorial on the basic authentication flow in OAuth 1.0, and then subsequently through the specification.