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.

1
2
3
4
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<AuthenticationInfo>
	<Username>abolte</Username>
</AuthenticationInfo>

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".

1
2
3
  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<Entities TotalResults="2128">
<Entity Type="defect">
...

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.