Rest API Documentation
Most data stored in the Valispace database is accessible in machine-readable (.json) format through a REST API. You can find it at http://yourdeployment.valispace.com /rest/

The REST API is very powerful and gives you direct read/write access to your data. However, with great power comes great responsibility. In case you would like to write your own application which can interface with Valispace, don't hesitate to contact us to support you.
The following chapters describe the Valispace API endpoints.
Request a token
Because of our latest security improvements and upgrades in order to request a token is necessary to execute the http request using the content type x-www-form-urlencoded
.
On the payload should be added the parameters grant_type
, client_secret
, client_id
, username
and password
. The grant_type
parameter needs to have the value ”password”
Examples:
Data:
client_id: "client"
client_secret: "secret"
password: "password"
username: "username"
Using curl
curl --location --request POST '<domain>/o/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_secret=secret' \
--data-urlencode 'client_id=client' \
--data-urlencode 'username=username' \
--data-urlencode 'password=password'
Using python requests
import requests
url = "<domain>/o/token/"
payload='grant_type=password&client_secret=secret&client_id=client&username=username&password=password'
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Request an Authorization Token
Please check this documentation to help on this process using django admin preparation https://www.liip.ch/en/blog/authorization-code-with-pkce-on-django-using-django-oauth-toolkit
To learn more about what is a code_challenge please check this good information https://www.valentinog.com/blog/challenge/#what-is-the-code-challenge
Component
Components are the hierarchical elements in your component tree, which describe your product structure. Use the Components API calls to manage components in your Valispace deployment.
POST /rest/component
Body parameters
Parameter | Data type | Required / optional | Description |
---|---|---|---|
name | String | required | The name of the component. Only letters, numbers and underscores are allowed. |
project | Int | required, if parent is null | The id of the project which this component will belong to. If the parent field is set, the project field will be overwritten by the project of the parent component. |
parent | Int | optional | The id of the desired parent component. If left empty, the component will be added to the top level of the specified project. If left empty, the project field is required. |
description | String | optional | A description text of this component. |
tags | list | optional | An optional list of existing tag ids which will be added to this component. |
GET /rest/component/{component-id}
Gets the component properties for a specific component.
Response parameters
Parameter | Data type | Description |
---|---|---|
id | Int | Unique id of the component. |
name | String | Name of component. |
unique_name | String | The unique name of this component contructed by prepending the parent name(s) until a unique name is found. Example: |
description | String | Description of this component. |
parent | Int | Parent id. |
project | Int | Project id. |
tags | List of ints | List of tags (ids) which this component has. |
valis | List of ints | List of Valis (ids) which belong to this component. |
textvalis | List of ints | List of Textvalis (ids) which belong to this component. |
matrices | List of ints | List of Matrices (ids) which belong to this component. |
modelists | List of ints | List of Modelists (ids) which belong to this component. |
is_alternative_container | Boolean | True if this component is of type Alternative Container, meaning that it has alternatives/options which can be selected by the user. |
current_alternative | Int | The id of the currently selected alternative. Only applicable if the is_alternative_container field is True. |
alternatives | List of ints | List of ids of the alternatives of this component. Only applicable if the is_alternative_container field is True. |
specifications | List of ints | List of ids of Specifications from the requirements module, which are applicable to this component. |
instances | List of ints | List of ids of components which are connected copies of this component. Only applicable if this component is a connected copy. |
children | List of ints | List of ids of component which are children/subcomponents of this component. |
Vali
Valis are technical parameters that belong to a Component, Matrix, Analysis or Requirement. Use the Vali API calls to manage Valis in your Valispace deployment.
POST /rest/vali
Body parameters
Parameter | Data type | Required | Description |
---|---|---|---|
shortname | String | required | The name of the Vali, e.g. Mass or Power_consumption. Only letters, numbers and unserscores are allowed. |
parent | Int | required | The id of the object which the Vali will belong to. The object can be a Component, Analysis or Requirement |
formula | String | optional | The value of the Vali is calculated with the formula. If no formula is specified, the formula will default to "0". Valis can be used in formulas by specifying "${vali-id}". Examples of formulas are: "42" or "$12 * 200 / sin($524)". |
unit | String | optional | The unit associated with the value, e.g. kg or N. If the unit field is left blank, it will be left as dimensionless or automatically populated if the Vali has a formula which results in a unit. |
type | Int | optional | The id of the Valitype of the Vali. A Valitype can be for example Mass. Only Valis with a type have the possibility to use special formulas such as "soc()". |
margin_plus | Float | optional | Margin with which the higer limit case is calculated. The margin is specified in % of the value of the Vali, e.g. specifying 10 as margin_plus for a value of 20 kg, will give a worst case of 20 kg + 10% of 20 kg = 22 kg. |
margin_minus | Float | optional | Margin with which the lower limit case is calculated. The margin is specified in % of the value of the Vali, e.g. specifying 10 as margin_minus for a value of 20 kg, will give a worst case of 20 kg - 10% of 20 kg = 18 kg. |
minimum | Float | optional | Minimum requirement of this Vali, e.g. the Mass should be more than 10 kg. The unit is not sent in the request, but will be populated by the Vali unit. |
maximum | Float | optional | Maximum requirement of this Vali, e.g. the Mass should be less than 20.5 kg. The unit is not sent in the request, but will be populated by the Vali unit. |
description | String | optional | Description of this Vali. |
reference | String | optional | Reference where this Vali comes from, e.g. "Book XYZ, page 20" or a link to a website. |
tags | List of ids | optional | An optional list of existing tag ids which will be added to this Vali. |
symbolic_representation | String | optional | Shorter name of Vali which can be used as a representation in the formulas. Latex notation is used for displaying this in the Valispace UI. |
subscribed | Boolean | optional | Set to True if the user wants to subscibe to changes to this Vali and get notifications when it changes. |