ExApp lifecycle
The ExApp lifecycle is a set of communication rules (or protocol) between Nextcloud and ExApp. They are required as for the microservice architecture of ExApp. This section is an overview, more details on that here: App Installation Flow, Deployment.
ExApp lifecycle methods
When ExApp is being installed in Nextcloud, there are several lifecycle steps happening. The ExApp lifecycle requires the following API endpoint handlers (order is preserved):
healthcheck: Docker container healthcheck.
/heartbeat: [required] ExApp heartbeat handler.
/init: [optional] ExApp initialization handler.
/enabled: [required] ExApp enable/disable handler.
Healthcheck
Docker allows you to define a custom healthcheck script for your container (specified in the Dockerfile). You can define here if needed custom container startup logic.
Note
AppAPI healthcheck timeout is 15 minutes.
Heartbeat
The GET /heartbeat method is called periodically by Nextcloud to check the ExApp health status,
if its webserver is running and recieving requests.
URL: GET http://localhost:2345/heartbeat
AppAPI expects a response with HTTP status 200. This step fails if the ExApp does not respond within 10 minutes.
Note
This endpoint should be available without AppAPIAuth authentication.
There is a 10 minutes timeout for the ExApp to startup and respond to the /heartbeat request.
Init
The POST /init endpoint is called after the ExApp is enabled in Nextcloud.
This is a trigger for ExApp to start its initialization process, e.g. downloading models, starter data, etc.
Note
Default init timeout (init_timeout) is 40 minutes. It can be changed by admin in AppAPI settings
or via CLI command occ config:app:set app_api init_timeout --value 40 --type mixed.
URL: POST http://localhost:2345/init
AppAPI expects a response with HTTP status 200.
Note
If ExApp doesn’t not implement /init endpoint and AppAPI receives HTTP 501 NOT IMPLEMENTED or HTTP 404 NOT FOUND response,
AppAPI enables the ExApp.
The ExApp should update the init progress via the PUT /ocs/v2.php/apps/app_api/ex-app/status API request,
with { "progress": <number> } payload.
Enabled
The PUT /enabled?enabled=1|0 method is called when the ExApp is enabled or disabled in Nextcloud.
The enabled query parameter is used to determine the ExApp state: 1 - enabled, 0 - disabled.
PUT http://localhost:2345/enabled?enabled=1- enable ExApp, during this call ExApp should register all needed APIsPUT http://localhost:2345/enabled?enabled=0- disable ExApp, during this call ExApp should unregister all APIs
AppAPI expects a response with HTTP status 200. Any other status code will be considered as an error.
Note
AppAPI timeout for the enabled handler is 30 seconds.
ExApp lifecycle scheme
Let’s review a simple ExApp lifecycle scheme:
Nextcloud-side ExApp lifecycle methods
The Nextcloud-side ExApp lifecycle methods are the OCS APIs. You can find available AppAPI Nextcloud OCS APIs here.
Note
ExApp should register all needed APIs during the enabled method call.
E.g. UI (top-menu, filesactionmenu), occ commands, etc.
AppAPI Authentication
Nextcloud requests to the ExApp are secured with AppAPIAuth. The ExApp should validate the authentication using the same algorithm as AppAPI does.
Note
Is it up to the developer to apply the rate limits, bruteforce protection, and other security measures to the ExApp API endpoints.