Automation - REST API

MatrixALM/QMS has a REST API that can do everything that the application is doing.

Documentation

The API is described on Swagger here. 

We made some fixes in REST API documentation and some very minor changes inside REST API code.

These changes can be seen comparing the Swagger hub documentation between 2.3 and 2.4.

You can create a clone of the documentation in swagger itself to quickly run some tests against your instance:

If you want to use it on your instance, you need to create an account on a service that supports the use of OpenAPI 3.0 specifications, for example swagger.

Then you copy the whole definition text and you just change the following line:

- url: 'https://apidemo.matrixreq.com/rest/1'

to map it to your instance.

Using the API

In order to use the API you need to authenticate: you can do so by using tokens or a user /password combinations. We recommend using tokens.

You can run commands using any language and tools for rest APIs (or directly in your swagger playground).

As the whole UI goes exclusively through that API to access Matrix you can do anything you can do in the UI. Also if you have a doubt about one of the REST API methods, you can spy on the UI to see which calls it does.

Authentication

Tokens

To consume the API you need to authenticate through a token: you can create one through Matrix either in the administration client or the normal client. (see Tokens).

Important: if you create a new user account for the token, make sure that you also set a password for this user as it's needed to activate the account.

Note: Tokens are not stored in plain text. Upon creation, the token is displayed to the user only once, providing an opportunity to copy and store it safely. Afterward, existing tokens will be obfuscated in the user's UI Access Tokens window.

The authentication itself is done via an HTTP header:

Authorization: Token api_xxxx

Using token s in curl

So for example in curl

Using token s in swagger

Once you created 'your' swagger documentation playground, you need to save the token to be used through the Authenticate button:

Alternate authentication: BASIC

If you have no way to create a token for some reason, you could also use the older BASIC protocol. Be aware that the access to the API is much slower in that case, the checking of the password at each call is taking a lot of time

The authentication itself is also done via an HTTP header:

Authorization: BASIC x64

with x64 the base64 encoding of the string user:password

Data structure

The data structure of the API maps 1-to-1 the concepts in the UI.

Projects have different categories (REQ, TC, DOC, ...)

Each category has a list of possible fields

Each item belong to a category and a folder

Each item has a reference (REQ-1), a title, a set of field values (the fields defined in its category), and a list of labels

Labels are defined in a project setting and explain which label can be defined in which category.

If you have comments about the above please reach our support.