REST-API: Apps

Erzeugt aus dem OpenAPI-Dokument des Daemons. Konventionen, Anmeldung, der CSRF-Header und der WebSocket stehen unter API.

GET /api/apps

Administrators only. Every installed app with its manifest, permissions, uid and state, and the app pool. The topic apps/admin carries the same and its changes.

Antworten

• 200: application/json: AdminAppList

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

PATCH /api/apps/{appId}

Administrators only. Enables or disables an app. A disabled app keeps its data and grants, but nobody can open it, its frontend is not served and its tokens end.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Anfrage-Body: application/json: UpdateAppRequest

Antworten

• 200: application/json: AppDetails

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

DELETE /api/apps/{appId}

Administrators only. Removes an app as a job and answers 202 with it: data=keep removes its frontends and keeps its data on the app pool for a later install of the same app, data=delete destroys its dataset with every snapshot. Its grants go either way.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja
data	query	string	ja

Antworten

• 202: application/json: Job

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

GET /api/apps/{appId}/grants

Administrators only. Who may use an installed third-party app: the grants of users and groups on app: (the built-in group users stands for everybody) and every user’s result.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Antworten

• 200: application/json: AppGrants

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

PUT /api/apps/{appId}/grants

Administrators only. Replaces the grants of users and groups on the app, each with level allow; without any, only administrators use it. Applies at once and is pushed to the users’ desktops.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Anfrage-Body: application/json: AppGrantsRequest

Antworten

• 200: application/json: AppGrants

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

GET /api/apps/{appId}/icon

The icon of an app the user may use (any app for administrators), served with Content-Security-Policy: default-src ‘none’; sandbox.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Antworten

• 200: image/svg+xml: string (byte)

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

PUT /api/apps/{appId}/log-level

Administrators only. Switches the app’s debug log entries on (debug) or off (info, the default); info, warn and error always reach the Log Center. The topic apps carries the level to the app’s windows.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Anfrage-Body: application/json: AppLogLevelRequest

Antworten

• 200: application/json: AppDetails

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

PUT /api/apps/{appId}/permissions

Administrators only. Grants or revokes permissions the app’s manifest asks for (app.permission.not_requested for any other); the listed ones change, the others stay. A revoked permission stays revoked across updates. Users’ windows of the app learn it with their next token (A11).

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Anfrage-Body: application/json: AppPermissionsRequest

Antworten

• 200: application/json: AppDetails

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

POST /api/apps/{appId}/rollback

Administrators only. Goes back to the version before the app’s last update as a job: the app’s dataset returns to the snapshot of that update, so its data goes back too, and the previous version runs again (app.app.no_previous without one).

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Antworten

• 202: application/json: Job

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

PUT /api/apps/{appId}/storage/{storageId}

Administrators only. Maps an existing folder of a shared folder to a storage request of the app’s manifest, replacing an earlier mapping: read-only, or read and write when the request asks for it (app.mapping.invalid otherwise). The folder keeps its rights, snapshots and backups and survives an uninstall.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja
storageId	path	string	ja

Anfrage-Body: application/json: AppStorageMappingRequest

Antworten

• 200: application/json: AppDetails

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

DELETE /api/apps/{appId}/storage/{storageId}

Administrators only. Removes the folder mapped to a storage request of the app; the folder itself stays.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja
storageId	path	string	ja

Antworten

• 200: application/json: AppDetails

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

POST /api/apps/{appId}/tokens

A token for an app the signed-in user may use (any app for administrators; app.app.not_found otherwise), bound to the user, this session, the app and the window instance, valid 5 minutes. kind host is for the daemon’s API for apps (/api/app/**) and stays in the desktop; kind backend is for the app’s backend (app.backend.missing without one). Needs the session cookie and the CSRF header; ask again before expiresAt.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Anfrage-Body: application/json: AppTokenRequest

Antworten

• 200: application/json: AppToken

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

PUT /api/apps/{appId}/update-policy

Administrators only. The app’s own update policy (automatic, notify, none), or null to follow the box’s.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
appId	path	string	ja

Anfrage-Body: application/json: AppUpdatePolicyRequest

Antworten

• 200: application/json: AppDetails

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

PUT /api/apps/packages

Administrators only. Streams an app package (-.pithyxapp, a gzip-compressed tar archive) as the raw body, at most 256 MB with 512 MB of files. Unpacks and checks it (archive, layout, manifest, icon; ids under org.pithyx.* are refused) and keeps it for 15 minutes for its installation by the same administrator. Answers with what installing it would do, including the permission changes of an update.

Antworten

• 200: application/json: AppPackagePreview

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

GET /api/apps/packages/{packageId}

Administrators only. The check result of an uploaded package again, while it is kept (app.package.not_found otherwise).

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
packageId	path	string	ja

Antworten

• 200: application/json: AppPackagePreview

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

DELETE /api/apps/packages/{packageId}

Administrators only. Discards an uploaded package without installing it.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
packageId	path	string	ja

Antworten

• 204

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

POST /api/apps/packages/{packageId}/install

Administrators only. Installs or updates the app from an uploaded package as a job and answers 202 with it. The first app needs pool, the pool for every app’s data; access (everybody by default) decides who may use a newly installed app. An update takes a snapshot of the app’s dataset first and returns to it when a step fails.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
packageId	path	string	ja

Anfrage-Body: application/json: InstallAppRequest

Antworten

• 202: application/json: Job

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.