Currently I am playing with the REST API of HP ALM and since some basics are always good before you start automating things, I first wanted to connect to ALM using a web browser.
Authentication
Open a browser and type in the following url, but replace the part {host} with the address to your HP ALM server.
https://{host}/qcbin/authentication-point/authenticate
This will display a simple login dialog, in which you provide your HP ALM user name and the corresponding password.
After a successful login you will see an empty / blank page.
In order to check, if you really are logged on to ALM, type in the following url.
https://{host}/qcbin/rest/is-authenticated
The result will be a simple xml stating your user name, if you are successfully logged into ALM.
If you are not authenticated, the server will deliver the following result.
HTTP ERROR 401
Problem accessing /qcbin/rest/is-authenticated. Reason:
Authentication failed. Browser based integrations - to login append '?login-form-required=y to the url you tried to access.
Do not let this message let confuse you to append ?login-form-required=y to the provided url. At least for me on ALM version 11.52 it did not work. Instead use https://{host}/qcbin/authentication-point/authenticate to authenticate.
Example - Reading Defects
Now we can start to send queries to HP ALM in order to read for example all defects to an XML file.
After successful authentication provide the following url in order to read all defects from HP ALM.
https://{host}/qcbin/rest/domains/{domain}/projects/{project}/defects
Replace the following parameters in the url and send it.
{host} = the address of your HP ALM server
{domain} = a name of a domain in hp alm holding 1 to n projects
{project} = a name of a project in a provided domain
The result will be an xml file holding information on all defects currently available in your queried HP ALM project.
Data Paging
When a query returns a large amount of records, the result is separated into several pages. This automated restriction of returned records per page is configured on server side and you will not be able to change this setting unless you have access to HP ALM Site Administration. In the end this setting is meant to protect the servers performance.
However you are able to use the page-size parameter in an URL in order to change the amount of returned records within the configured limit of maximum returned records.
An URL would look as follows.
/qcbin/rest/domains/{domain}/projects/{project}/tests?page-size=20
The above would return 20 records per page.
The limitations applied depend on the HP ALM Site Administration settings and follow the rules in below table.
Parameter Name | Default | Applies if ... | Site Admin Parameter |
Default Page Size | 100 | Applies if the parameter is not set in Site Administration | REST_API_DEFAULT_PAGE_SIZE |
Maximum Page Size | 2.000 | Applies if the parameter is not set in Site Administration | REST_API_MAX_PAGE_SIZE |
If you want to know what the maximum page size of your server is, use the following configuration.
page-size=max
The number of totally available results is located at the document start in the Attribute "TotalResults".
In order to call the next page you have to append the parameter start-index to an URL.
http://SERVER:PORT/qcbin/rest/domains/{domain}/projects/{project}/defects?page-size=10&start-index=31
Why using REST instead of OTA API?
The big advantage the REST API has compared to the old OTA API is you do not need any client components anymore since you just place a http / https request at the server and it delivers an HTPP or XML result depending on your request.
Why is that good for users? Because they do not have to bother with braking software components on the clients anymore. Also the quite complex installation of client components is not necessary anymore. I can remember times where I had to provide support for many people in a company where the installation of client components had not been packaged yet. It was a mess, since users had to do it themselves and the second level support (so me) had to help the first level support whenever a new project was created in HP ALM for many users.
For HP the REST API is more efficient than the old client side OTA API anyway.