List update candidates belonging to an app version

GET/v2/apps/{appId}/versions/{baseAppVersionId}/update-candidates

API version

Request method

GET

Operation ID

app-list-update-candidates-for-appversion

Request

appIdstring (uuid)required
baseAppVersionIdstring (uuid)required

Responses

Response headers

X-Pagination-Limitinteger
X-Pagination-Skipinteger
X-Pagination-TotalCountinteger

Format

application/json

Description

Object containing the list of AppVersions.

Array[
An AppVersion is an officially supported version of an App, containing the necessary and recommended configuration und dependencies.
- *object
  An AppVersion is an officially supported version of an App, containing the necessary and recommended configuration und dependencies.
  - appIdstring (uuid)required
  - backendPathTemplatestring
  - breakingNoteobject
    A BreakingNote is a hint that something serious has changed in the AppVersion containing it, so an automatic update is not possible.
    - faqLinkstring (uri)required
  - databasesarray of object
    - Array[
      A DatabaseDependency is a generic description of need for a database, used by AppVersions.
      - *object
        A DatabaseDependency is a generic description of need for a database, used by AppVersions.
        descriptionstringrequired
        kind"mysql"required
        parametersobject
        *string
        versionstring (uuid)required
      ]
  - defaultCronjobsarray of object
    - Array[
      - *object
        activebooleanrequired
        commandobject
        interpreterTemplatestringrequired
        parametersTemplatestring
        pathTemplatestringrequired
        descriptionstringrequired
        intervalstringrequired
        timeoutinteger (int32)required
        urlTemplatestring
      ]
  - docRootstringrequired
  - docRootUserEditablebooleanrequired
  - externalVersionstringrequired
  - idstring (uuid)required
  - internalVersionstringrequired
  - recommendedboolean
  - requestHandlerobject
    RequestHandlerRequirement describes the necessary properties to internally resolve the request handler or process to start.
    - exampleValuesarray of object
      - Array[
        A SavedUserInput is an entered value for a desired UserInput of an AppVersion or SystemSoftwareVersion.
        *object
        A SavedUserInput is an entered value for a desired UserInput of an AppVersion or SystemSoftwareVersion.
        namestringrequired
        valuestringrequired
        ]
    - namestringrequired
    - namespacestringrequired
    - parametersTemplatestringrequired
  - systemSoftwareDependenciesarray of object
    - Array[
      A SystemSoftwareDependency is a description of a need for a specific SystemSoftware in a semver versionRange.
      - *object
        A SystemSoftwareDependency is a description of a need for a specific SystemSoftware in a semver versionRange.
        systemSoftwareIdstring (uuid)required
        versionRangestringrequired
      ]
  - updateConstraintstring
    SemVer constraint that newer AppVersions must satisfy to be eligible as automatic update targets for this AppVersion.
  - userInputsarray of object
    - Array[
      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.
      - *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.
        additionalValidationSchemaobject
        AdditionalValidationSchema is a stringified custom validation schema, e.g password rules.
        kind"password-rule"
        AdditionalValidationSchemaKind is an enum, describing the possible types of an additional validation schema.
        schemastring
        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.
        namestringrequired
        positionMetaobject
        UserInputPositionMeta is a utility information, helping to position the UserInput properly on the frontend.
        indexinteger
        sectionstring
        stepstring
        requiredbooleanrequired
        validationSchemastringrequired
        JSON Schema formatted (https://json-schema.org/‍).
      ]
]

Content-Type: application/json

[
  {
    "appId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "backendPathTemplate": "string",
    "breakingNote": {
      "faqLink": "string"
    },
    "databases": [
      {
        "description": "string",
        "kind": "mysql",
        "parameters": {
          "string": "string"
        },
        "version": "f0f86186-0a5a-45b2-aa33-502777496347"
      }
    ],
    "defaultCronjobs": [
      {
        "active": true,
        "command": {
          "interpreterTemplate": "bash",
          "parametersTemplate": "-c",
          "pathTemplate": "/bin/bash"
        },
        "description": "Beschreibung des Cronjobs",
        "interval": "0 5 * * *",
        "timeout": 300,
        "urlTemplate": "https://example.com/cronjob"
      }
    ],
    "docRoot": "string",
    "docRootUserEditable": true,
    "externalVersion": "string",
    "id": "f0f86186-0a5a-45b2-aa33-502777496347",
    "internalVersion": "string",
    "recommended": true,
    "requestHandler": {
      "exampleValues": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "name": "string",
      "namespace": "string",
      "parametersTemplate": "string"
    },
    "systemSoftwareDependencies": [
      {
        "systemSoftwareId": "f0f86186-0a5a-45b2-aa33-502777496347",
        "versionRange": "string"
      }
    ],
    "updateConstraint": "string",
    "userInputs": [
      {
        "additionalValidationSchema": {
          "kind": "password-rule",
          "schema": "string"
        },
        "dataSource": "string",
        "dataType": "text",
        "defaultValue": "string",
        "format": "email",
        "lifecycleConstraint": "installation",
        "name": "string",
        "positionMeta": {
          "index": 123,
          "section": "string",
          "step": "string"
        },
        "required": true,
        "validationSchema": "string"
      }
    ]
  }
]

{
  "items": {
    "description": "An AppVersion is an officially supported version of an App, containing the necessary and recommended configuration und dependencies.",
    "properties": {
      "appId": {
        "format": "uuid",
        "type": "string"
      },
      "backendPathTemplate": {
        "type": "string"
      },
      "breakingNote": {
        "description": "A BreakingNote is a hint that something serious has changed in the AppVersion containing it, so an automatic update is not possible.",
        "properties": {
          "faqLink": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "faqLink"
        ],
        "type": "object"
      },
      "databases": {
        "items": {
          "description": "A DatabaseDependency is a generic description of need for a database, used by AppVersions.",
          "properties": {
            "description": {
              "type": "string"
            },
            "kind": {
              "enum": [
                "mysql"
              ],
              "type": "string"
            },
            "parameters": {
              "additionalProperties": {
                "type": "string"
              },
              "type": "object"
            },
            "version": {
              "format": "uuid",
              "type": "string"
            }
          },
          "required": [
            "version",
            "description",
            "kind"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "defaultCronjobs": {
        "items": {
          "properties": {
            "active": {
              "example": true,
              "type": "boolean"
            },
            "command": {
              "properties": {
                "interpreterTemplate": {
                  "example": "bash",
                  "type": "string"
                },
                "parametersTemplate": {
                  "example": "-c",
                  "type": "string"
                },
                "pathTemplate": {
                  "example": "/bin/bash",
                  "type": "string"
                }
              },
              "required": [
                "interpreterTemplate",
                "pathTemplate"
              ],
              "type": "object"
            },
            "description": {
              "example": "Beschreibung des Cronjobs",
              "type": "string"
            },
            "interval": {
              "example": "0 5 * * *",
              "type": "string"
            },
            "timeout": {
              "example": 300,
              "format": "int32",
              "type": "integer"
            },
            "urlTemplate": {
              "example": "https://example.com/cronjob",
              "type": "string"
            }
          },
          "required": [
            "interval",
            "active",
            "description",
            "timeout"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "docRoot": {
        "type": "string"
      },
      "docRootUserEditable": {
        "type": "boolean"
      },
      "externalVersion": {
        "type": "string"
      },
      "id": {
        "format": "uuid",
        "type": "string"
      },
      "internalVersion": {
        "type": "string"
      },
      "recommended": {
        "type": "boolean"
      },
      "requestHandler": {
        "description": "RequestHandlerRequirement describes the necessary properties to internally resolve the request handler or process to start.",
        "properties": {
          "exampleValues": {
            "items": {
              "description": "A SavedUserInput is an entered value for a desired UserInput of an AppVersion or SystemSoftwareVersion.",
              "properties": {
                "name": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "value"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "namespace": {
            "type": "string"
          },
          "parametersTemplate": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "namespace",
          "parametersTemplate"
        ],
        "type": "object"
      },
      "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",
        "uniqueItems": true
      },
      "updateConstraint": {
        "description": "SemVer constraint that newer AppVersions must satisfy to be eligible as automatic update targets for this AppVersion.",
        "type": "string"
      },
      "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": {
            "additionalValidationSchema": {
              "description": "AdditionalValidationSchema is a stringified custom validation schema, e.g password rules.",
              "properties": {
                "kind": {
                  "description": "AdditionalValidationSchemaKind is an enum, describing the possible types of an additional validation schema.",
                  "enum": [
                    "password-rule"
                  ],
                  "type": "string"
                },
                "schema": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "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": "integer"
                },
                "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",
        "uniqueItems": true
      }
    },
    "required": [
      "id",
      "appId",
      "externalVersion",
      "internalVersion",
      "docRoot",
      "docRootUserEditable"
    ],
    "type": "object"
  },
  "type": "array"
}

Format

application/json

Description

Your request ran into a rate limit. You have to wait until rate limit expires

messagestring
typestring

Content-Type: application/json

{
  "message": "too many requests",
  "type": "RateLimitError"
}

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "too many requests"
    },
    "type": {
      "type": "string",
      "example": "RateLimitError"
    }
  }
}

Format

application/json

Description

An unexpected Error that occurred while handling the request

messagestringrequired
typestringrequired

Content-Type: application/json

{
  "message": "Something went wrong",
  "type": "InternalServerError"
}

{
  "type": "object",
  "required": [
    "type",
    "message"
  ],
  "properties": {
    "message": {
      "type": "string",
      "example": "Something went wrong"
    },
    "type": {
      "type": "string",
      "example": "InternalServerError"
    }
  }
}

Usage examples

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/apps/f0f86186-0a5a-45b2-aa33-502777496347/versions/f0f86186-0a5a-45b2-aa33-502777496347/update-candidates?onlyRecommended=true

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.listUpdateCandidatesForAppversion({
  "appId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "baseAppVersionId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "queryParameters": {
    "onlyRecommended": true
  }
});

assertStatus(response, 200);
  

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

$request = (new ListUpdateCandidatesForAppversionRequest(
  appId: "f0f86186-0a5a-45b2-aa33-502777496347",
  baseAppVersionId: "f0f86186-0a5a-45b2-aa33-502777496347"
))
  ->withOnlyRecommended(true);
$response = $client->app()->listUpdateCandidatesForAppversion($request);

var_dump($response->getBody();
  

List update candidates belonging to an app version

Request​

Path parametersrequired

Query parameters

Responses​

OK200

Too Many Requests429

default

Usage examples​

On this page

Request

Responses

Usage examples