Skip to main content
Skip table of contents

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.