Rest API and Python API Documentation

This document provides the reference for the Valispace REST API. Using the REST API, the users can get and modify data from Valispace or even write data back into Valispace and thus update information. Additionally, this gives you the possibility to connect/integrate with other applications or apps.

Authentication for integrating applications

If you want to integrate valispace with another application/software, the authentication is implemented via OAuth. The user needs to create a new application entry, create a client ID and client secret, and provide an authorization grant type.
The users can create the client ID and client Secret in the admin panel, search for “Django OAuth toolkit”, and then select applications.

To access the admin panel, the user need to contact the admins of the deployment. To access the admin panel you can add “/admin" to the deployment name. eg. models.valispace.com/admin

Do not forget to copy the client secret and store it somewhere safe. After saving the application, the client secret gets hashed and the user cannot see it anymore.

With the created application in the admin panel, the user can use this above-created information to log in to valispace. Here’s one of the example of the script to connect to valispace. You can copy and modify the information for your use case.

curl --location 'http://deployment_name/o/token/' \
--header 'X-Request-ID: ' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'password=Your_password' \
--data-urlencode 'username=Your_username' \
--data-urlencode 'client_id=Your_client_id' \
--data-urlencode 'client_secret=Your_client_secret'

Once the above code is run, an access token will be generated. This access token is temporary and expires at a certain time. You can use the refresh token for this case.

Response example

{
    "access_token": "hO2lwhLZsYOgXPNVIs6vBzqSp",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "read write groups",
    "refresh_token": "fyig40fP97MFBKQsf1Y7b"
}

Here’s an example to refresh the token

curl --location 'http://deployment_name/o/token/' \
--header 'X-Request-ID: sadfas' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_secret=your_client_Secret' \
--data-urlencode 'client_id=your_client_id' \
--data-urlencode 'refresh_token=fyig40fP97MFBKQZK'

Consuming the API using the access_token, adding a token through a "Bearer ..." using the application type "JSON" to the Authorization HTTP request header is necessary.

curl --location 'http://deployment_name/rest/requirements/versions/search/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer hO2lwhLZsYOgXPNVI' \
--data '{
    "size": 10,
    "query_filters": {
        "object_id": 93
    }
}'

Also, you can use the requests to log in to valispace. Here’s the example code where you can add the missing information.

import requests

USERNAME = "your_username_here"
PASSWORD = "your_password_here"
CLIENT_ID = "your_client_id"
CLIENT_SECRET = "your_client_Secret"
DOMAIN_URL = "deployment_name"

##### GET THE ACCESS TOKEN
access_token_url = f"{DOMAIN_URL}/o/token/"
response = requests.post(
    url=access_token_url,
    data={
        "grant_type": "password",
        "username": USERNAME,
        "password": PASSWORD,
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    }
)

assert response.status_code == 200
response_data = response.json()
print(response_data)

ACCESS_TOKEN = response_data["access_token"]

Python API Documentation

The Valispace python API lets you access and update objects in your Valispace deployment with python code.

Install the Valispace python API with pip:

CODE

pip install valispace

Copy

Import valispace API module in a python script:

CODE

import valispace

Copy

and initialize with

CODE

valispace = valispace.API()

Copy

More information about the functionalities and functions in the API can be found at github.com/valispace/ValispacePythonAPI. The Valispace python API is licensed under the MIT license, which means that anyone can contribute to the code by cloning the GitHub repository.

Endpoints

The users can access the endpoints on the rest page. To access the page, add “rest/”at the end of the deployment name. eg: “models.valispace.com/rest/”. This page lists all the existing endpoints

To access the rest page, use your deploymentname.valispace.com/rest/. Leaving out the “/” at the end of the rest doesn't redirect you to the rest page.

There are “GET”,” POST”,” PUT”,” PATCH” and “DELETE” methods.

Every object in Valispace has its own ID; you can use it to look for and retrieve the object information itself. The object ID can be seen either directly in Valispace or in the URL when clicking on the object in Valispace.

For example, if you use the get function to get vali information through the rest, you can use the following endpoint to get the vali details.

GET /rest/valis/{vali-id}/

Similarly, you can use the methods to retrieve/update or post different objects such as components, tags, valis, textvalis, requirements, specifications, verification methods, etc. You can search for the endpoints on the rest page.

Filtering objects for projects

In addition to authentication, you can use the "GET" method to retrieve objects such as Valis or Requirements within the deployment. If you need to filter the results based on a specific project, you can achieve this by leveraging the filtering capabilities, provided the endpoint is configured accordingly. For instance, to retrieve requirements associated with project 24, you can use the following GET request:

GET /rest/requirements/?project=24

This functionality is demonstrated in the video below for a clearer understanding.

Inbuilt functions

Within valispace, whenever a user types the text in the text field, the text is saved in the backend in the HTML
format. The HTML format retains the formatting references to valis or other objects. So, if you are getting the requirements information, you might get the HTML text in your import. To avoid this, we have implemented two functions which can be useful to convert the HTML fields to just text or HTML formatting with valis converted to text. The functions are clean_text and clean_html.

Clean_text function

The clean text function converts all the HTML formats and object references within the field to text. However, in this case, the formatting is also lost. For example, the formatting is also lost if you have a list, tables or colour. You can use this as shown below.

GET /rest/requirements/?project=24&clean_text=text,rationale

Here, I am doing the filter for project 24 and asking to give the clean text for the text and rationale of the field. The output would be this for this specific action.

Clean_html function

The clean_html function keeps the formatting options of the text but then converts the references/objects like valis to text. If the text contains formatting options such as lists, background colour, tables etc, this information is retained.

GET /rest/requirements/?project=24&clean_html=text,rationale

Common Questions:

How to find the correct endpoint?

Navigating through numerous endpoints with similar names can be confusing. If you ever find uncertainty about a specific endpoint, we encourage you to contact our support channel for clarification. Alternatively, you can leverage your browser's "network" feature to observe which endpoints are triggered when performing actions within the software's front end.

As an illustration, consider the process of creating a component. In this case, the associated endpoint can be identified as a "POST" request to "/rest/components," this information can be easily discerned by inspecting the network activity during the action. A concise demonstration of this approach is provided in the brief video below.

How do you get/post a requirement's verification methods(VM) and components?

A requirement in Valispace can be associated with multiple verification methods (VMs), each of which can, in turn, have multiple components attached to it. Various verification method types are supported, including rules, test, inspection, analyses, review, and custom VMs. Each verification method type is uniquely identified by its own ID.

You can use the appropriate endpoint to retrieve the IDs for these verification method types.

GET /rest/requirements/verification-methods/

For example, to obtain the IDs of Verification method types for project id 24, you can use the following endpoint

GET /rest/requirements/verification-methods/?project=24

To obtain the verification methods linked to a specific requirement, Valispace creates a dedicated object known as "Requirement-VMS." This object has its unique identifier (ID), which can be accessed through the following endpoint:

GET /rest/requirements/requirement-vms/

For example, this requirement, SPC-002 with ID 2165 has one verification method of type “Rules”, and the object id of requirment-vms is 2203.

If we use the endpoint, “/rest/requirements/requirement-vms/2203 ” we get the following response.

Upon inspection of the "Requirement-vms" object, you'll notice that the method ID "20" corresponds to the "Rules" Verification Method, as per the list of verification method types obtained earlier. When incorporating this information into your script, ensure that you map the method ID to the respective verification method type.

Furthermore, within the "Requirement-vms" object, there are references to two component VMs. These component-VM IDs represent the components attached to the Requirement Verification Methods. When interacting with these components programmatically, utilize these IDs in your script accordingly.

The endpoint to access the component-vms would be

GET /rest/requirements/component-vms/{id}

When you get the details of the component vms, the component fields gives you the component id with which you can map the component’s name.