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.