List system software versions belonging to a system software

GET/system-software/{systemSoftwareId}/versions/

API version

v2

Request method

GET

Operation ID

app-list-systemsoftwareversions

---

Request

• systemSoftwareIdstring (uuid)

  required

Responses

Response headers

• X-Pagination-Limitnumber
• X-Pagination-Skipnumber
• X-Pagination-TotalCountnumber

Format

application/json

Description

Object containing the list of SystemSoftwareVersions.

Schema documentation

• Array[
• *object

  A SystemSoftwareVersion is an officially supported version of a SystemSoftware, containing the necessary and recommended configuration und dependencies.

  • expiryDatestring (date-time)
  • externalVersionstring

    required
  • feeone of 2 alternatives

    A strategy for fees of resources.

  • idstring (uuid)

    required
  • internalVersionstring

    required
  • recommendedboolean
  • systemSoftwareDependenciesarray of object
    • Array[
    • *object

      A SystemSoftwareDependency is a description of a need for a specific SystemSoftware in a semver versionRange.

      • systemSoftwareIdstring (uuid)

        required
      • versionRangestring

        required
    ]
• userInputsarray of object
  • Array[
  • *object

    A UserInput is a description of an information which cannot be determined or estimated by mittwald, but has to be given by the person who is requesting an AppInstallation or SystemSoftware.

    • dataSourcestring

      Optional field to tell the frontend, which data to put into the select.

    • dataTypestring (one of: text, number, boolean, select)

      required

      UserInputDataType is an enum, describing the possible data types of a UserInput.

    • defaultValuestring
    • formatstring (one of: email, password, url, uri)

      UserInputFormat is an enum, describing the possible data formats of a UserInput, the given values can be validated against.

    • lifecycleConstraintstring (one of: installation, update, reconfigure)

      required

      The AppInstallationLifecycle can be used to express a specific point in the AppInstallation Lifecycle, e.g. while installing a new AppInstallation.

    • namestring

      required
    • positionMetaobject

      UserInputPositionMeta is a utility information, helping to position the UserInput properly on the frontend.

      • indexnumber
      • sectionstring
      • stepstring
    • requiredboolean

      required
    • validationSchemastring

      required

      JSON Schema formatted (https://json-schema.org/).

  ]

]

Example

[
  {
    "expiryDate": "2024-11-08T18:07:27.189Z",
    "externalVersion": "string",
    "fee": {
      "price": 123
    },
    "id": "f0f86186-0a5a-45b2-aa33-502777496347",
    "internalVersion": "string",
    "recommended": true,
    "systemSoftwareDependencies": [
      {
        "systemSoftwareId": "f0f86186-0a5a-45b2-aa33-502777496347",
        "versionRange": "string"
      }
    ],
    "userInputs": [
      {
        "dataSource": "string",
        "dataType": "text",
        "defaultValue": "string",
        "format": "email",
        "lifecycleConstraint": "installation",
        "name": "string",
        "positionMeta": {
          "index": 123,
          "section": "string",
          "step": "string"
        },
        "required": true,
        "validationSchema": "string"
      }
    ]
  }
]

JSON Schema

{
  "items": {
    "description": "A SystemSoftwareVersion is an officially  supported version of a SystemSoftware, containing the necessary and recommended configuration und dependencies.",
    "properties": {
      "expiryDate": {
        "format": "date-time",
        "type": "string"
      },
      "externalVersion": {
        "type": "string"
      },
      "fee": {
        "description": "A strategy for fees of resources.",
        "oneOf": [
          {
            "description": "A strategy for fees that occur once.",
            "properties": {
              "price": {
                "description": "The one-time price in Euro Cents.",
                "type": "number"
              }
            },
            "required": [
              "price"
            ],
            "type": "object"
          },
          {
            "description": "A strategy for fees that occur periodically",
            "properties": {
              "periods": {
                "items": {
                  "properties": {
                    "feeValidFrom": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "feeValidUntil": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "monthlyPrice": {
                      "description": "The monthly price in Euro Cents.",
                      "type": "number"
                    }
                  },
                  "required": [
                    "monthlyPrice"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "periods"
            ],
            "type": "object"
          }
        ]
      },
      "id": {
        "format": "uuid",
        "type": "string"
      },
      "internalVersion": {
        "type": "string"
      },
      "recommended": {
        "type": "boolean"
      },
      "systemSoftwareDependencies": {
        "items": {
          "description": "A SystemSoftwareDependency is a description of a need for a specific SystemSoftware in a semver versionRange.",
          "properties": {
            "systemSoftwareId": {
              "format": "uuid",
              "type": "string"
            },
            "versionRange": {
              "type": "string"
            }
          },
          "required": [
            "systemSoftwareId",
            "versionRange"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "userInputs": {
        "items": {
          "description": "A UserInput is a description of an information which cannot be determined or estimated by mittwald, but has to be given by the person who is requesting an AppInstallation or SystemSoftware.",
          "properties": {
            "dataSource": {
              "description": "Optional field to tell the frontend, which data to put into the select.",
              "type": "string"
            },
            "dataType": {
              "description": "UserInputDataType is an enum, describing the possible data types of a UserInput.",
              "enum": [
                "text",
                "number",
                "boolean",
                "select"
              ],
              "type": "string"
            },
            "defaultValue": {
              "type": "string"
            },
            "format": {
              "description": "UserInputFormat is an enum, describing the possible data formats of a UserInput, the given values can be validated against.",
              "enum": [
                "email",
                "password",
                "url",
                "uri"
              ],
              "type": "string"
            },
            "lifecycleConstraint": {
              "description": "The AppInstallationLifecycle can be used to express a specific point in the AppInstallation Lifecycle, e.g. while installing a new AppInstallation.",
              "enum": [
                "installation",
                "update",
                "reconfigure"
              ],
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "positionMeta": {
              "description": "UserInputPositionMeta is a utility information, helping to position the UserInput properly on the frontend.",
              "properties": {
                "index": {
                  "type": "number"
                },
                "section": {
                  "type": "string"
                },
                "step": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "required": {
              "type": "boolean"
            },
            "validationSchema": {
              "description": "JSON Schema formatted (https://json-schema.org/).",
              "type": "string"
            }
          },
          "required": [
            "name",
            "dataType",
            "validationSchema",
            "lifecycleConstraint",
            "required"
          ],
          "type": "object"
        },
        "type": "array"
      }
    },
    "required": [
      "id",
      "internalVersion",
      "externalVersion"
    ],
    "type": "object"
  },
  "type": "array"
}

Usage examples

cURL

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/system-software/f0f86186-0a5a-45b2-aa33-502777496347/versions?versionRange=string&recommended=true

JavaScript SDK

import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
  
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.app.listSystemsoftwareversions({
  "systemSoftwareId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "queryParameters": {
    "versionRange": "string",
    "recommended": true
  }
});

assertStatus(response, 200);
  

PHP SDK

use \Mittwald\ApiClient\Generated\V2\Clients\App\ListSystemsoftwareversions\ListSystemsoftwareversionsRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new ListSystemsoftwareversionsRequest(
  systemSoftwareId: "f0f86186-0a5a-45b2-aa33-502777496347"
))
  ->withVersionRange("string")
  ->withRecommended(true);
$response = $client->app()->listSystemsoftwareversions($request);

var_dump($response->getBody();