Squash TM Rest API 1.0.1

112 Pages·2017·0.68 MB·English

Squash TM Rest API 1.0.2
Benoît Siri
Table of Contents
Overview
What you can do with it
What you cannot do with it
The basics
Base URL
API versioning
Supported HTTP methods
HTTP status codes
Response format
Rel Names
Identifying and locating an Entity
Unauthorized resources
Entity extensions
Authentication
Common query parameters
Entity Reference
Attachments
Get attachment
Rename attachment
Download attachment
Upload attachment
Delete attachment
Automated Execution Extenders
Get automated execution extender
Automated Suites
Get all automated suites
Get automated suite
Get automated execution extenders of automated suite
Create automated suite from iteration
Create automated suite from iteration test plan items
Create automated suite from test suite
Execute automated suite
Automated Tests
Get automated test
Campaigns
Get all campaigns
Get campaign
Get iterations of campaign
Get test plans of campaign
Campaign Folders
Get all campaign folders
Get campaign folder
Get campaign folder contents
Campaign Test Plan Items
Get campaign test plan item
Datasets
Get dataset
Executions
Get execution
Modify an execution
Get steps of execution
Execution Steps
Get execution step
Modify status of execution step
Iterations
Get iteration
Get test plans of an iteration
Get test suites of an iteration
Iteration Test Plan Items
Get iteration test plan item
Get executions of iteration test plan item
Create execution for iteration test plan item
Parameters
Get parameter
Projects
Get all projects
Create project
Create project template
Get project
Get project permissions
Add permissions to project
Get campaigns of project
Get requirements of project
Get test cases of project
Get campaign library contents
Get requirement library contents
Get test case library contents
Requirements
Get all requirements
Create requirement
Get requirement
Delete requirement
Get requirement children
Requirement Folders
Get all requirement folders
Get requirement folder
Get requirement folder contents
Requirement Versions
Get requirement version
Teams
Get all teams
Create team
Get team
Modify team
Delete team
Get team members
Add members
Remove members
Test Automation Servers
Get all test automation servers
Get test automation server
Test Cases
Get all test cases
Create test case
Get test case
Modify test case
Get datasets of test case
Get parameters of test case
Get steps of test case
Test Case Folders
Get all test case folders
Get test case folder
Get test case folder contents
Test Steps
Get test step
Modify test step
Delete test step
Create test step
Test Suites
Get test suite
Get plans of test suite
Users
Get all users
Create user
Get user
Modify user
Delete user
Get user subscribed teams
Subscribe to teams
Unsubscribe from teams
This plugin provides Squash TM with REST-like services (but not exactly like rest), that is, a
set of services implemented with a resource-first approach, that allows you to interact
with the business without a GUI, by exchanging json representations of those resources
via HTTP requests.
Overview
In few words, here is what you will be able/unable to do with this version (1.0.2) of the API:
What you can do with it
read operations on most of the business domains
create, update and delete services on some of the business domains
setup projects
have support for attachments and automated tests
benefit from this present documentation
What you cannot do with it
explore links or use a self-discovery function
have support for issues
The basics
In the following documentation, the words Resource and Entity have the same meaning unless the context
uses both. When a distinction is made, we generally mean that:
an Entity repesents an actual element of the business model (test case, project, etc)
a Resource represents any data exchanged with the server. This includes the entities and other kinds of
data (paged collections and other things)
Base URL
The API publishes its services under the root URL {squash root url}/api/rest/latest/.
So in a common case, it could be http://localhost:8080/squash/api/rest/latest/.
API versioning
For now, and in a foreseeable future, no versioning of the API is planned. As it stands, the plugin is not
ready for multiple concurrent deployment. The placeholder /latest/ that stands for the version
number in the API base URL does not make much sense for now; but it makes it future-proof if such a
feature is implemented down the road.
Supported HTTP methods
The API supports the following methods (verbs):
Table 1. HTTP methods
Method Usage
GET Requests resource(s) from the server
POST Submits new resources to the server
PATCH Submits modifications of an existing resource
DELETE Requests suppression of one or several resources
HTTP status codes
The system replies with conventional HTTP statuses, here is a short reminder:
Table 2. HTTP status
Status Meaning
2S0ta0t OusK TMheea onpinergation completed successfully.
201 Created A new resource has been created. The response body returns a representation of
that resource.
204 No Content The operation completed successfully and the server returned no response body.
400 Bad Request The request is malformed.
401 Unauthorized The user is not authenticated, or supplied wrong credentials.
403 Forbidden The user’s request is denied.
404 Not Found The resource doesn’t exist.
412 Preconditions Failed The submitted resource creation/modification request is rejected because it would
leave the resource in an invalid state.
500 Internal Server Error An error occured while the request was processed.
Response format
The only format supported by the API is JSON. This implies that HTTP requests to and from the API may
forgo the headers Accept: application/json and Content-Type: application/json (even if they
are accepted and formally correct). The naming convention for the attribute is snake_case.
Rel Names
What we call the rel name (relation name) of an entity is the type of the entity as represented in an URI or
in its json representation. They come in two forms: singular and plural. Both are expressed in lowercase,
hyphenated names based on the entity type. The root path of the URI uses the plural form (e.g. /test-
cases), and the json representation of an entity uses the singular form (e.g. "type" : "test-case").
Conceptually the singular name characterizes a single, actual instance of that entity (this is why it is one
of the identifier properties), while the plural name represents the whole family of entities. Unless stated
otherwise, the plural form is just composed of the singular form suffixed with an 's'. In some cases, the
singular and plural forms are different, and it is often a sign of a polymorphic entity. For instance the
script of a test case is composed of several steps that may either describe an action and expected behavior
(test-step), or describe a reference to another test case (call-step), yet both are unified under the
family of test-steps.
See chapter Entity Reference for a list of known rel names.
Identifying and locating an Entity
Business entities, in particular, share three common properties, that tell you or the system how to identify
and locate the entity. Those properties are called identifier properties.
Example : minimal representation of a test case folder
{
"_type" : "test-case-folder",
"id" : 10,
"_links" : {
"self" : {
"href" : "http://localhost:8080/squash/api/rest/latest/test-case-folders/10"
}
}
}
The _type here is the hyphenated lowercase name of the entity type.
This is the id of that instance of the entity.
These are the related links, which always contain a self-reference. Note that the _links attribute may look
like the HAL format, but it is really not similar: the API serves no cURI nor templated URIs.
The server will always include those attributes when rendering an entity - either as a single response or
as part of a deep cluster of entities -, and can never be disabled (see Parameter 'fields').
On one hand, a client posting/ patching a json entity to the server is not required to specify them all. Only
the _type is always required even when it is implied by the URI. Furthermore, the request will fail if the
_type contradicts the target endpoint URI. On the other hand the id and _links are ignored without
consequences.
for REST formalists: the Content-Type is always application/json, there are no
dedicated MIME type per resource. Those three attributes are the only one that exist.
Unauthorized resources
When a client requests a resource it is not allowed to read, the server replies with HTTP 403 and a json
representation of the error.
Sometimes the client requests a resource it is not allowed to read, but it is not the case of the related
resources. This may happen for instance when two related resources (e.g. a test case and a requirement)
belong to different projects yet the client is allowed to read the content for only one of them. In that case,
those relations will be rendered as unauthorized resources instead of being omitted or considered as
leaked information. That way, the user is aware that a relation indeed exists without knowing all the
details.
Example of unauthorized resources:
{
"_type" : "test-case",
"id" : 4567,
...,
"verified_requirements": [
{
"_type": "unauthorized-resource",
"resource_type": "requirement-version",
"resource_id": 256,
"_links": {
"self": {
"href": "http://localhost:8080/squash/api/rest/latest/requirement-versions/256"
}
}
}
],
...
}
The client can access the content of the test case as usual.
The _type here is the special type unauthorized-
resource.
This is the real type of the unauthorized resource.
This is the id of the unauthorized resource.
By following this link, you will result in a proper 403.
Entity extensions
Some business entities can be attached with a module that provides support for additional features. Those
features are optional and those modules will appear in the json representation only if your projects
actually use them. For instance the executions, in a context of test automation, will be attached with a
module named AutomatedExecutionExtender that hosts on Squash-TM the test results produced by a
remote test server.
Such extenders are commonly named with a -extender suffix. From the REST API perspective, these
extension are managed like any other entities.
Example of an automated execution:
{
"_type" : "execution",
"id" : 56,
"name" : "sample test case 56",
"execution_order" : 4,
"execution_status" : "BLOCKED",
"execution_mode" : "AUTOMATED",
"automated_execution_extender" : {
"_type" : "automated-execution-extender",
"id" : 778,
"_links" : {
"self" : {
"href" : "http://localhost:8080/api/rest/latest/automated-execution-extenders/778"
}
}
},
...
}
The type here is still execution : although it supports automated testing, the type has not fundamentally
changed (i.e. there is no such thing as an AutomatedExecution).
The property automated_execution_extender is defined here but would not appear in a regular, manual
execution.
Authentication
REST client should use the Basic Authentication. Remember that this protocol is considered as insecure if
it is used without encryption.
If you prefer to explore the API using your browser, the session cookie obtained via the
login page will also be valid.
Common query parameters
Throughout this documentation you will often find several recurrent query parameters. Rather than
detailing them over and over at each documentation site, we prefer to explain them all here.
Pagination parameters
When the requested resource is a collection of other resources/entities, the underlying service often
comes with a pagination feature. We call them the paginated resources. Pagination allows you to define
pages of entities and browse from one page to another, instead of simply retrieving all the data in one
row. It is actually enabled by default, because neither the server nor you would like to swallow possibly
several thousands elements at once!
Pagination is driven by a couple of parameters appended to the resource URI:
size: it is an integer that defines how many elements should be returned by page. Of course it should
be of at least 1 and may have arbitrary large value. The default value is 20.
page: it shows you the page you are requesting. Pages are numbered from 0 onward. Negative value
will be treated as 0. Default value is 0 (which corresponds to the first page).
Paginated resources are often served with extra attributes _links and page to guide you through your
navigation.
Example of a paginated query:
curl 'http://localhost:8080/squash/api/rest/latest/test-cases?page=2&size=1' -i -H 'Accept: application/json'
{
"_embedded": {
"test-cases": [
{
"_type": "test-case",
"id": 239,
"name": "Defensive opening",
"reference": "",
"_links": {
"self": {
"href": "http://localhost:8080/squash/api/rest/latest/test-cases/239"
}
}
}
]
},
"_links": {
"first": {
"href": "http://localhost:8080/squash/api/rest/latest/test-cases?page=0&size=1"
},
"prev": {
"href": "http://localhost:8080/squash/api/rest/latest/test-cases?page=1&size=1"
},
"self": {
"href": "http://localhost:8080/squash/api/rest/latest/test-cases?page=2&size=1"
},
"next": {
"href": "http://localhost:8080/squash/api/rest/latest/test-cases?page=3&size=1"
},
"last": {
"href": "http://localhost:8080/squash/api/rest/latest/test-cases?page=5&size=1"
}
},
"page": {
"size": 1,
"totalElements": 6,
"totalPages": 6,
"number": 2
}
}
It represents the links to the first, previous, current, next and last page. Other query parameters (such as the
size) are left untouched.
It represents the attributes of the current page. It also states how many elements you can read this way, and
therefore how many pages can be viewed in total.
The content of _links is contextual, and only links with sense will be proposed. Consider, for instance, a
page large enough to gather all the available entities; this page would be the one and only page available.
In that case the only link would be a self-reference, because it would be the first and the last page, and
there are no existing pages before nor after.
Sorting paginated resources
That feature is so unsupported that it should be considered as a side effect.
The query parameter sort allows you to specify one or several attributes of the entity under
consideration, followed by the (optional) sorting direction. Eg, &sort=attr1[,attr2…][,asc|desc]. It
may work for certain attributes and not for others.
Also note that sorting is disabled for certain paginated resources because the order of the content is
important and must be kept. This is the case for a test script for example: it makes no sense to sort it by,
id or action, for example.
Parameter 'include'
That parameter, when possible, lets you choose how to deal with hierarchies of entities. Squash TM
primarily organizes its business domain in several file tree (one per project) of arbitrary depth. When
requesting the content of a container, you may choose one of the following value:
root: only the direct children nodes are considered by your request. This is the default.
nested: the request should also consider any node that belongs to the subtree of the entity under
consideration.
You can combine this with other pagination parameters to limit the returned content.
Example: find everything contained in a folder
curl 'http://localhost:8080/squash/api/rest/latest/test-case-folders/15/content?page=0&size=10&include=nested' -i -H 'Accept: application/json'
Parameter '(cid:47)elds'
That query parameter lets you define with a filter expression which attributes of an entity you want to
have in the response.
A filter expression is a comma-separated list of property names. A star '*' is a wild card that stands for all
the properties. If a property name is prefixed with a minus '-', that property will be excluded from the
rendering, overriding the wild card if present.
Filter expressions can be nested using brackets '[' and ']''. If a nested filter is defined for a property, it will
apply to the value(s) of that property. It is primarily used when the said value is a complex object, a
relation of the current entity, or a collection of such. Primary types will remain unaffected. You can nest
filters within nested filters and so on.
If a filter expression remains empty, every property will be rendered if the current entity is the root of the
cluster targeted by the request, or none for other entities. This rule prevents the engine to crawl forever
through an entity cluster, especially if it holds circular references. However, because of this you must
explicitly specify a nested expression for each property that requires it, otherwise they will appear empty
(except for the identifier properties, see above). To that end, you may redeclare a nested expression for a
property even when a '*' was specified if you wish to see more of the relation accessed to by that
property.
In all cases, the identifier properties id, \_type and _links of an entity will always be included: a filter
expression never needs to include them explicitly, and they can never be disabled with the '-' operator.
Table 3. Example: valid filter expressions (applied to a test-case):
Expression Effect
id,label,reference Renders the properties label, reference and the
identifier properties (including id).
id,label,steps[action, Renders the id, label and test steps. The steps will
called_test_case[name,reference]] include the identifier properties, the action to be
accomplished and the called_test_case in case the
step is a call step. The called test cases will be
rendered with their properties name and reference
(and identifier properties).
* Will render all the properties of the test case.
However, relations such as the test steps will be
rendered with bare bones properties.
*,steps[action] Will render all the properties of the test case. Its
relations will be rendered with bare bones
properties, except for the test steps that will also
include their actions.
*,-reference Will render all the properties as stated above, minus
the reference.
Table 4. Example: invalid filter expressions
Expression Problem
label,steps[action A closing bracket is missing, the expression is
unbalanced.
label,steps[action]],reference The root filter expression exited early, the expression
is unbalanced.
Example: usage of the parameter filter
curl 'http://localhost:8080/squash/api/rest/latest/test-cases?page=0&size=10&fields=label,last_modified_by' -i -H 'Accept: application/json'
Entity Reference
Most resource URIs are built around the pattern /<plural-rel-name>[/<id>[/component]] (see Rel
Names). The following table is a list of the resources known to help you find the URLs you need.