Update properties belonging to an app installation
PATCH/app-installations/ {appInstallationId}/
This API operation can be used to modify an existing app installation. This includes the following changes:
- Changing the app version
- Changing the system software dependencies (like PHP and other system components)
- Changing the configuration parameters (
userInputs)
Usage notes
Determining possible update candidates for appVersionId
When performing a version upgrade, the target version is identified by the appVersionId body parameter.
To determine the app ID of an existing app installation, use the GET/ operation. The response of this operation contains the appId and appVersion.current properties which contain the relevant IDs.
Using the app ID, you can use the GET/ operation to determine possible versions that you can upgrade to.
Determining possible system softwares
When changing the system software dependencies of an app installation, you can use the GET/ operation to determine the possible system software dependencies that you can set.
You can also use the GET/ operation to determine the system software dependencies of a specific app version. The response of this operation contains a .systemSoftwareDependencies property which contains the relevant system software IDs, along with a semantic version range of compatible versions.
Removing system software dependencies
Due to the semantics of the HTTP PATCH request, omitting a system software entirely from the request body will mean "leave unchanged". To explicitly uninstall a system software dependency, explicitly set it to null:
PATCH /v2/app-installations/{appInstallationId} HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json
{
"systemSoftware": {
"34220303-cb87-4592-8a95-2eb20a97b2ac": null
}
}
On user inputs
Pay attention to the userInputs parameter in the request body. This parameter is a list of objects, each with a name and value property.
The allowed values for name are dependent on the app version being installed. To determine the required inputs for a given app version, inspect the userInputs property of the app version object returned by the unknown operation app-list-appversion operation.
Request
Responses
Usage examples
- cURL
- PHP SDK
- JavaScript SDK
$ curl \
--fail \
--location \
-X PATCH \
-d '{"appVersionId":"f0f86186-0a5a-45b2-aa33-502777496347","customDocumentRoot":"string","description":"string","systemSoftware":{"string":{"systemSoftwareVersion":"string","updatePolicy":"none"}},"updatePolicy":"none","userInputs":[{"name":"string","value":"string"}]}' \
-H "Authorization: Bearer $MITTWALD_API_TOKEN" \
-H 'Content-Type: application/json' \
https://api.mittwald.de/v2/app-installations/f0f86186-0a5a-45b2-aa33-502777496347
use \Mittwald\ApiClient\Generated\V2\Clients\App\PatchAppinstallation\PatchAppinstallationRequest;
use \Mittwald\ApiClient\Generated\V2\Clients\App\PatchAppinstallation\PatchAppinstallationRequestBody;
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));
// TODO: Please consult the properties and constructor signature of
// PatchAppinstallationRequestBody to learn how to construct a valid instance
$body = new PatchAppinstallationRequestBody(/* TODO: ... */);
$request = (new PatchAppinstallationRequest(
appInstallationId: "f0f86186-0a5a-45b2-aa33-502777496347",
body: $body
));
$response = $client->app()->patchAppinstallation($request);
var_dump($response->getBody();
Update to the latest possible version:
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const appInstallationId = "<insert uuid here>";
// Retrieve app installation from API
const installationResponse = await client.app.getAppinstallation({
appInstallationId,
});
assertStatus(installationResponse, 200);
// Get versions to update to
const candidatesResponse = await client.app.listUpdateCandidatesForAppversion({
"appId": installationResponse.data.appId,
"baseAppVersionId": installationResponse.data.appVersion.current
});
assertStatus(candidatesResponse, 200);
// Get recommended version
const recommendedVersion = candidatesResponse.data.find(version => version.recommended);
// Perform the update
const response = await client.app.patchAppinstallation({
appInstallationId,
"data": {
"appVersionId": recommendedVersion.id,
}
});
assertStatus(response, 204);
Update PHP to latest compatible version:
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const appInstallationId = "<insert uuid here>";
const phpSoftwareId = "34220303-cb87-4592-8a95-2eb20a97b2ac";
// Retrieve app installation from API
const installationResponse = await client.app.getAppinstallation({
appInstallationId,
});
assertStatus(installationResponse, 200);
// Retrieve app version metadata
const versionResponse = await client.app.getAppversion({
appVersionId: installationResponse.data.appVersion.current
});
assertStatus(versionResponse, 200);
const phpVersionRange = versionResponse.data.systemSoftwareDependencies.find(dep => dep.systemSoftwareId === phpSoftwareId).versionRange;
const phpVersionsResponse = await client.app.listSystemsoftwareVersions({
"systemSoftwareId": phpSoftwareId,
"versionRange": phpVersionRange
});
assertStatus(phpVersionsResponse, 200);
// Get recommended version
const recommendedVersion = phpVersionsResponse.data.find(version => version.recommended);
// Perform the update
const response = await client.app.patchAppinstallation({
appInstallationId,
"data": {
"systemSoftware": {
[phpSoftwareId]: {
"systemSoftwareVersion": recommendedVersion.id
}
}
}
});
assertStatus(response, 204);