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: `Rocket.Engine.Combustion_chamber` for a component with name `Combustion_chamber`.
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.