diff --git a/developer_manual/basics/front-end/l10n.rst b/developer_manual/basics/front-end/l10n.rst index 97fc8528d..a31ca9c47 100644 --- a/developer_manual/basics/front-end/l10n.rst +++ b/developer_manual/basics/front-end/l10n.rst @@ -335,6 +335,8 @@ That would sync the translations for the branches (``main`` and ``master`` are a If you need help just `open a ticket with the request `_ and we can also guide you through the steps. +.. _manual-translation: + Manual translation ^^^^^^^^^^^^^^^^^^ diff --git a/developer_manual/exapp_development/DevSetup.rst b/developer_manual/exapp_development/DevSetup.rst index 75c7a66e6..7e5411bc1 100644 --- a/developer_manual/exapp_development/DevSetup.rst +++ b/developer_manual/exapp_development/DevSetup.rst @@ -5,7 +5,7 @@ Setting up dev environment AppAPI development requires a Nextcloud development environment setup. We highly recommend using `Julius Knorr's Docker setup `_ for this. -For an alternate environment without using Docker, please refer to the `Nextcloud development environment docs `_. +For an alternate environment without using Docker, please refer to the setup instructions in :doc:`Getting started <../getting_started/devenv>`. Suggested IDE: **PhpStorm**, though you can certainly use any IDE of your preference such as **VS Code** or **Vim**. @@ -50,14 +50,18 @@ Deploy daemons types There are two types of Deploy daemons that can be used for development and testing of ExApps: 1. ``manual_install``: This type of Deploy daemon is running manually in the host machine. - You can create it in AppAPI admin settings using template. - This is useful for development of ExApp, when you run your ExApp manually in the host. + This is useful for ExApp development as you can run your ExApp directly on the host. 2. ``docker_install``: This type of Deploy daemon is running in a Docker container. +You can register (create) these daemons in the AppAPI admin settings. +For the equivalent ``occ`` command or an explanation of the Deploy daemon parameters, +see :ref:`occ_daemon_config_registration`. + Docker Socket Proxy ******************* -For development and testing locally, the simplest is to use the `Nextcloud AppAPI DSP HTTP `_. +For development and testing locally, +the simplest way is to use the `Nextcloud AppAPI DSP HTTP `_. In Place of a Conclusion """""""""""""""""""""""" diff --git a/developer_manual/exapp_development/development_overview/ExAppDevelopmentSteps.rst b/developer_manual/exapp_development/development_overview/ExAppDevelopmentSteps.rst index e35f3fd30..673dd7966 100644 --- a/developer_manual/exapp_development/development_overview/ExAppDevelopmentSteps.rst +++ b/developer_manual/exapp_development/development_overview/ExAppDevelopmentSteps.rst @@ -3,35 +3,35 @@ ExApp development ================= -ExApp development process is similar to the development of the regular Nextcloud PHP app, -and should follow the same guidelines in terms of security, design and coding style (`ref `_) +The ExApp development process is similar to that of a regular Nextcloud (PHP) app, +and should follow the same guidelines in terms of security, design and coding style (see :doc:`../../getting_started/development_process` for details) based on your programming language standards. Despite the fact, that ExApp can be developed in any language, it's still recommended to have the understanding -of the Nextcloud `PHP request life cycle `_ and other basic concepts, +of the Nextcloud :doc:`PHP request lifecycle <../../basics/request_lifecycle>` and other basic concepts, as they are usually similar to the ExApp backend to which Nextcloud communicates. -You can think about ExApp like a microservice (Docker container) +You can think of each ExApp as a microservice (Docker container) that runs separately from Nextcloud on the Deploy daemon, which can be remote or local. -The communication between Nextcloud and ExApp is done via network secured with AppAPI authentication (:ref:`app_api_auth`). +The communication between Nextcloud and ExApp is done via network secured with :doc:`AppAPIAuth <../tech_details/Authentication>`. -Lets go through the ExApp development steps briefly. +Let's go through the ExApp development steps briefly. 0. Setting up the development environment ----------------------------------------- -First of all, you need to have a Nextcloud dev setup, refer to :ref:`dev-setup` for more details. +First, you need to have a Nextcloud dev setup, refer to :doc:`../DevSetup` for more details. 1. Starting from template ------------------------- -Next step, is to setup the ExApp skeleton. +Next is to setup the ExApp skeleton. There are several ExApp examples available so you can have a look at them and start from. The ExApp template and examples: - ``[Python]`` `App Skeleton `_ - ``[Python]`` `UI Example Skeleton `_ - - ``[Python]`` `More complex ExApp UI example with 3rdparty service `_ + - ``[Python]`` `More complex ExApp UI example with 3rd-party service `_ - ``[GoLang]`` `Go Lang ExApp example `_ - etc. @@ -49,20 +49,20 @@ More details are available in the :ref:`ExAppOverview` section. 3. Development -------------- -The development process basically contains from the following steps: +The basic development process contains from the following steps: - Implement the ExApp <-> Nextcloud :ref:`lifecycle methods `: - #. ``/heartbeat``: ExApp heartbeat method. - #. ``/init``: ExApp initialization method. - #. ``/enabled``: ExApp enable/disable method. -- Implement the ExApp backend API and logic. -- Implement the ExApp frontend (Nextcloud Vue.js app) [optional]. + #. ``/heartbeat``: ExApp heartbeat method + #. ``/init``: ExApp initialization method + #. ``/enabled``: ExApp enable/disable method +- Implement the ExApp backend API and logic +- Implement the ExApp frontend (Nextcloud Vue.js app) [optional] 4. Packaging ------------ -The ExApp packaging can be done manually, or via GitHub actions. +The ExApp packaging can be done manually or via GitHub actions. It is recommended to use GitHub actions for packaging, as it will automate the process of building the Docker image and pushing it to the Docker registry. The GitHub action workflow for building Docker images can be found in the `3rdparty service example `_. @@ -88,7 +88,7 @@ Dockerfile ********** The Dockerfile is required to build the Docker image for the ExApp. -The guideline for writing the Dockerfile can be found in the `Dockerfile best practices `_. +The guidelines for writing the Dockerfile can be found in the `Dockerfile best practices `_. Short recommendations: @@ -100,10 +100,10 @@ Short recommendations: Logging ******* -The logs in Docker container are shown from the standard output and error streams. -To be able admin to see the important logs from ExApp container, +The Docker container logs are shown in the standard output and error streams. +For the admin to be able to see the important logs from the ExApp container, you should consider redirecting the logs to the standard output and standard error streams. -More info in `official docs for logging `_. +For more info, see `the official docs for logging `_. 5. AppStore publishing @@ -118,7 +118,6 @@ It's the same as for the regular Nextcloud app, but with the requirement of :ref ---------- It is important to ensure that your ExApp works as expected. -We recommend to have different types of dev setup configuration to test all of them. +We recommend having different types of dev setup configurations to test all of them. While the main development is done locally via ``manual_install``, you must also ensure that -the ExApp works correctly in Docker container with http and https Docker Socket proxy. - +the ExApp works correctly in a Docker container with Docker Socket Proxy (HTTP and HTTPS). diff --git a/developer_manual/exapp_development/development_overview/ExAppLifecycle.rst b/developer_manual/exapp_development/development_overview/ExAppLifecycle.rst index 693246388..1129b8e15 100644 --- a/developer_manual/exapp_development/development_overview/ExAppLifecycle.rst +++ b/developer_manual/exapp_development/development_overview/ExAppLifecycle.rst @@ -3,7 +3,7 @@ ExApp lifecycle =============== -The ExApp lifecycle is a set of communication rules (or protocol) between Nextcloud and ExApp. +The ExApp lifecycle is a set of communication rules (or protocols) between Nextcloud and the ExApp. They are required as for the microservice architecture of ExApp. This section is an overview, more details on that here: :ref:`app_installation_flow`, :ref:`app_deployment`. @@ -14,31 +14,31 @@ This section is an overview, more details on that here: :ref:`app_installation_f 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): +When the ExApp is being installed in Nextcloud, there are several lifecycle steps happening. +The ExApp lifecycle requires the following API endpoint handlers (in order): - - 0. ``healthcheck``: Docker container healthcheck. - - 1. ``/heartbeat``: **[required]** ExApp heartbeat handler. - - 2. ``/init``: **[optional]** ExApp initialization handler. - - 3. ``/enabled``: **[required]** ExApp enable/disable handler. + 0. ``healthcheck``: Docker container healthcheck + 1. ``/heartbeat``: **[required]** ExApp heartbeat handler + 2. ``/init``: **[optional]** ExApp initialization handler + 3. ``/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. +You can define any custom container startup logic here if needed. .. note:: - AppAPI healthcheck timeout is 15 minutes. + The 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 receiving requests. +i.e. if its webserver is running and receiving requests. URL: ``GET http://localhost:2345/heartbeat`` @@ -48,7 +48,7 @@ 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. + There is a 10 minute timeout for the ExApp to startup and respond to the ``/heartbeat`` request. .. _ex_app_lifecycle_init: @@ -58,12 +58,12 @@ 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. +This is a trigger for the 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``. + The default init timeout (``init_timeout``) is 40 minutes. It can be changed in the AppAPI admin settings + or via the command ``occ config:app:set app_api init_timeout --value 40 --type mixed``. URL: ``POST http://localhost:2345/init`` @@ -71,11 +71,11 @@ 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. + Even if the ExApp does not not implement ``/init`` endpoint and AppAPI receives a ``HTTP 501 NOT IMPLEMENTED`` or ``HTTP 404 NOT FOUND`` response, + AppAPI can still enable 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": }`` payload. +The ExApp should update the init progress via the ``PUT /ocs/v2.php/apps/app_api/ex-app/status`` API request +containing a ``{ "progress": }`` payload. Enabled @@ -92,7 +92,7 @@ AppAPI expects a response with HTTP status 200. Any other status code will be co .. note:: - AppAPI timeout for the ``enabled`` handler is 30 seconds. + The AppAPI timeout for the ``enabled`` handler is 30 seconds. ExApp lifecycle scheme @@ -132,19 +132,19 @@ You can find available AppAPI Nextcloud OCS APIs :ref:`here `, :ref:`filesactionmenu `), :ref:`occ commands `, etc. + The ExApp should register all needed APIs during the ``enabled`` method call, + such as the UI (:ref:`top-menu `, :ref:`filesactionmenu `), :ref:`occ commands `, etc. AppAPI Authentication --------------------- -Nextcloud requests to the ExApp are secured with :ref:`AppAPIAuth `. +Nextcloud requests to the ExApp are secured with :doc:`AppAPIAuth <../tech_details/Authentication>`. 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 + Is it up to the developer to apply rate limits, bruteforce protection, and other security measures to the ExApp API endpoints. diff --git a/developer_manual/exapp_development/development_overview/ExAppOverview.rst b/developer_manual/exapp_development/development_overview/ExAppOverview.rst index e2b16e52c..1ee545e4d 100644 --- a/developer_manual/exapp_development/development_overview/ExAppOverview.rst +++ b/developer_manual/exapp_development/development_overview/ExAppOverview.rst @@ -12,7 +12,7 @@ ExApp structure The typical ExApp folder structure is the following: -- **appinfo/**: contains the ExApp metadata, which is based on the regular `Nextcloud PHP appinfo `_, +- **appinfo/**: contains the ExApp metadata, which is based on the regular :doc:`Nextcloud PHP appinfo <../../app_development/info>`, but with additional new fields under the ``external-app`` key. - **ex_app/**: the ExApp specific folder, which contains the ExApp frontend and backend parts. - **lib/**: contains the ExApp backend part, which can be written in any language. @@ -58,7 +58,7 @@ The only requirement here is to follow the microservice architecture and ExApp < There is a limitation of AppAPI ExApp proxy - the websocket connections are not supported. -Each ExApp container has the environment variables set by AppAPI; you can find out more about them :ref:`here `. +Each ExApp container has environment variables set by AppAPI; you can find out more about them :ref:`here `. Persistent storage ****************** @@ -133,7 +133,7 @@ The same applies to the frontend API requests to the ExApp backend API: L10n translations ----------------- -Currently, only `manual translations `_ are supported. +Currently, only :ref:`manual translations ` are supported. To add support of your programming language from translations string extraction using Nextcloud translation tool, you just need to add your file extensions to it `in createPotFile `_ and down below adjust the ``--language`` and ``keyword`` parameters. @@ -238,7 +238,7 @@ It is recommended to use the following default set of commands: - ``build-push-cpu``: builds the Docker image for CPU and uploads it to the Docker registry. - ``build-push-cuda``: builds the Docker image for CUDA and uploads it to the Docker registry. - ``build-push-rocm``: builds the Docker image for ROCm and uploads it to the Docker registry. -- ``run``: installs the ExApp for Nextcloud latest via the ``occ app_api:app:register`` command, like from UI. +- ``run``: installs the ExApp for Nextcloud latest via the ``occ app_api:app:register`` command, like from the UI. - ``register``: performs registration of running manually ExApp using the ``manual_install`` Deploy daemon. - ``translation_templates``: execute translationtool.phar to extract translation strings from sources (frontend and backend). - ``convert_translations_nc``: converts translations to Nextcloud format files (json, js). @@ -247,5 +247,5 @@ It is recommended to use the following default set of commands: .. note:: These Makefiles are typically written to work in the `nextcloud-docker-dev `_ development environment. -For a complete example, you can take a look at our `Makefile for the Visionatrix app `_. +For a complete example, you can take a look at our `Makefile for the 3rd-party service example `_. This example also requires the ``xmlstarlet`` program to be installed so that the Makefile can automatically detect the ExApp version from the info.xml file. diff --git a/developer_manual/exapp_development/faq/BehindCompanyProxy.rst b/developer_manual/exapp_development/faq/BehindCompanyProxy.rst index ffe3f5b52..bee753a51 100644 --- a/developer_manual/exapp_development/faq/BehindCompanyProxy.rst +++ b/developer_manual/exapp_development/faq/BehindCompanyProxy.rst @@ -1,7 +1,7 @@ Corporate Proxy - Permanent Settings for PHP CLI ================================================ -If you're using our application within a corporate network that requires proxy settings, you might encounter issues when running PHP CLI commands that attempt to access the internet. +If you're using our application within a corporate network that requires proxy settings, you might encounter issues when running PHP CLI commands that attempt to access the Internet. To resolve this, you need to configure permanent proxy settings for the PHP CLI environment. @@ -28,12 +28,12 @@ This issue occurs because the PHP CLI environment does not have the proxy settin Permanent Solution ------------------ -To permanently configure proxy settings for PHP CLI, you can either modify the PHP CLI `php.ini` file or set environment variables system-wide. +To permanently configure proxy settings for PHP CLI, you can either modify the PHP CLI ``php.ini`` file or set environment variables system-wide. -Method 1: Edit PHP CLI `php.ini` File -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Method 1: Edit PHP CLI php.ini File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. **Locate the PHP CLI `php.ini` File** +1. **Locate the PHP CLI php.ini File** Run the following command to find the loaded configuration file for PHP CLI: @@ -47,9 +47,9 @@ Method 1: Edit PHP CLI `php.ini` File Loaded Configuration File: /path/to/php.ini -2. **Edit the `php.ini` File** +2. **Edit the php.ini File** - Open the `php.ini` file in a text editor with appropriate permissions: + Open the ``php.ini`` file in a text editor with the appropriate permissions: .. code-block:: bash @@ -94,16 +94,18 @@ Method 1: Edit PHP CLI `php.ini` File php occ app_api:app:register - It should now be able to access the internet through the proxy. + It should now be able to access the Internet through the proxy. -**Note:** Not all PHP functions respect the proxy settings in `php.ini`. If issues persist, consider using system-wide environment variables. +.. note:: + Not all PHP functions respect the proxy settings in ``php.ini``. + If issues persist, consider using system-wide environment variables. Method 2: Set System-Wide Environment Variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. **Edit Shell Profile** - For a permanent solution, add the proxy settings to the system-wide environment variables. Open the `/etc/environment` file: + For a permanent solution, add the proxy settings to the system-wide environment variables. Open the ``/etc/environment`` file: .. code-block:: bash @@ -138,7 +140,8 @@ Method 2: Set System-Wide Environment Variables It should now work without connectivity issues. -**Note:** This method sets the proxy settings for all users and applications on the system. +.. note:: + This method sets the proxy settings for all users and applications on the system. Troubleshooting --------------- @@ -153,7 +156,7 @@ Troubleshooting - **Firewall Restrictions** - Verify with your network administrator that your system is allowed to access the internet through the proxy. + Verify with your network administrator that your system is allowed to access the Internet through the proxy. Contact Support --------------- diff --git a/developer_manual/exapp_development/faq/DockerContainerRegistry.rst b/developer_manual/exapp_development/faq/DockerContainerRegistry.rst index ef77a512a..f8de00a3b 100644 --- a/developer_manual/exapp_development/faq/DockerContainerRegistry.rst +++ b/developer_manual/exapp_development/faq/DockerContainerRegistry.rst @@ -4,5 +4,5 @@ Docker Container Registry How to use a private Docker container registry with authentication? ******************************************************************* -Currently, we don't support the authentication for Docker container registry. +Currently, we don't support authentication for the Docker container registry. The ExApp images must be publicly available. diff --git a/developer_manual/exapp_development/faq/DockerSocketProxy.rst b/developer_manual/exapp_development/faq/DockerSocketProxy.rst index d26f5de8f..ada4e1af7 100644 --- a/developer_manual/exapp_development/faq/DockerSocketProxy.rst +++ b/developer_manual/exapp_development/faq/DockerSocketProxy.rst @@ -1,13 +1,13 @@ Docker Socket Proxy =================== -The recommended way to setup AppAPI Deploy daemon +The recommended way to setup the AppAPI Deploy daemon is to use our `Docker Socket Proxy implementation `_. Nextcloud AppAPI DSP -------------------- -Nextcloud AppAPI DSP (Docker Socket Proxy) - is a simple Docker container that provides a secure way to access the Docker Engine API and ExApps. +Nextcloud AppAPI DSP (Docker Socket Proxy) is a simple Docker container that provides a secure way to access the Docker Engine API and ExApps. It is secured with haproxy Basic authentication. There are two parts of reverse proxy configuration: @@ -24,23 +24,23 @@ There are two parts of reverse proxy configuration: Nextcloud AIO ------------- -Nextcloud AIO implements `Docker Socket Proxy container `_ which automatically setting up, -you just need to tick the checkbox in AIO configuration interface to enable it. -AppAPI automatically creates the default Deploy daemon configuration in Nextcloud AIO. +Nextcloud AIO implements its own `Docker Socket Proxy container `_; +you just need to tick the checkbox in the AIO configuration interface to enable it. +AppAPI automatically creates the default Deploy daemon configuration for Nextcloud AIO. See `Nextcloud in Docker AIO (all-in-one) `_ for more details. .. note:: Nextcloud AIO is not limited to its default Deploy daemon. - You can setup any other Deploy daemon (local or remote) to use it in AppAPI. + You can setup any other Deploy daemon (local or remote) for use in AppAPI. Other implementations --------------------- -Our implementation is inspired by `Tecnativa Docker Socket Proxy `_, -by default, it restricts access to the required by AppAPI Docker Engine APIs. +Our implementation is inspired by `Tecnativa Docker Socket Proxy `_. +By default, it restricts access to the required by AppAPI Docker Engine APIs. In this case, you will have to enable these APIs via the environment variables: - ``IMAGES=1`` @@ -49,7 +49,7 @@ In this case, you will have to enable these APIs via the environment variables: .. note:: - For local Deploy daemon setup other implementations of Docker Socket Proxy may be enough. + For local Deploy daemon setup, other implementations of Docker Socket Proxy may be enough. But for remote Deploy daemon setup, we recommend using our DSP, as `we allow `_ only the Docker Engine APIs we actually use in AppAPI, and it is additionally secured with haproxy authentication. diff --git a/developer_manual/exapp_development/faq/Scaling.rst b/developer_manual/exapp_development/faq/Scaling.rst index 79c1325c6..117bee5d2 100644 --- a/developer_manual/exapp_development/faq/Scaling.rst +++ b/developer_manual/exapp_development/faq/Scaling.rst @@ -1,22 +1,22 @@ Scaling ======= -AppAPI delegates the scaling task to the ExApps itself. -This means, that the ExApp must be designed in a way to be able to scale vertically. -As for the horizontal scaling, currently, it is not possible. -Except, for example, the Server-Workers architecture, is a good way to support basic scaling capabilities, -where the Server is your ExApp and the Workers are the external machines that can work with the ExApp +AppAPI delegates the scaling task to the ExApp itself. +This means that the ExApp must be designed in a way to be able to scale vertically. +As for the horizontal scaling, it is currently not possible except by using, +for example, a Server-Worker architecture, which is a good way to support basic scaling capabilities. +In this case, the Server is your ExApp and the Workers are the external machines that can work with the ExApp using Nextcloud user authentication. -Aadditional clients (or workers) can be (optionally) added (or attached) to the ExApp +Additional clients (or workers) can be (optionally) added (or attached) to the ExApp to increase the capacity and performance. GPUs scaling ------------ -Currently, if Deploy daemon configured with GPUs available, +Currently, if a Deploy daemon configured with GPUs available, AppAPI by default will attach all available GPU devices to each ExApp container on this Deploy daemon. -This means, that these GPUs are shared between all ExApps on the same Deploy daemon. -Therefore, for the ExApps that require GPU and uses it heavily, +This means that these GPUs are shared between all ExApps on the same Deploy daemon. +Therefore, for the ExApps that require heavy use of GPUs, it is recommended to have a separate Deploy daemon (host) for them. diff --git a/developer_manual/exapp_development/faq/Troubleshooting.rst b/developer_manual/exapp_development/faq/Troubleshooting.rst index 2b6c26530..01188a532 100644 --- a/developer_manual/exapp_development/faq/Troubleshooting.rst +++ b/developer_manual/exapp_development/faq/Troubleshooting.rst @@ -11,17 +11,17 @@ Networking issues can be not so straightforward to identify and resolve. Here are some common steps to verify the network configuration: - Verify that the Deploy daemon is running and accessible (AppAPI admin settings - Select Deploy daemon - Check connection). -- Verify the network mode and access levels, firewall, vpn, etc. +- Verify the network mode and access levels, firewall, VPN, etc. - Verify that Nextcloud is reachable from the Deploy daemon host - Verify that the Deploy daemon host is reachable from the Nextcloud host - Verify that Nextcloud is reachable from the ExApp container -- Verify if there is no DNS resolution issues -- Verify is there is no SSL certificate issues +- Verify that there are no DNS resolution issues +- Verify that there are no SSL certificate issues - If there are HTTP 401 Unauthorized errors, check the ExApp (``docker logs nc_app_``) / Nextcloud logs, on which API route it fails to authenticate, try to re-enable AppAPI and re-install the ExApp. .. note:: - If your case is not documented here, or doesn't exists on GitHub issues, - please feel free to ask it by creating an issue in the `AppAPI repository `_. + If your case is not documented here or doesn't exist in GitHub issues, + please feel free to ask by creating an issue in the `AppAPI repository `_. ExApp deployment issues @@ -39,15 +39,15 @@ Generally speaking, there are three steps to find the proper error message to un Failed to create volume ----------------------- -If you encounter "Failed to create volume" error, please check the following: +If you encounter a "Failed to create volume" error, please check the following: - Make sure that there is enough disk space on the host machine. - Check the Docker system logs while reproducing the issue (``journalctl -u docker.service``). -ExApps management list of apps from AppStore is empty ------------------------------------------------------ +ExApps management list of apps from App Store is empty +------------------------------------------------------ This issue may occur if you are loading the ExApps management (or regular Apps management) page -frequently during the short period of time and therefore your IP can be blocked by the AppStore rate-limits protection. -Please, wait for a while and try again. +frequently during the short period of time, and therefore your IP address can be blocked by the App Store rate-limits protection. +Please wait a while and try again. diff --git a/developer_manual/exapp_development/faq/index.rst b/developer_manual/exapp_development/faq/index.rst index 49629b54e..97dd9dddd 100644 --- a/developer_manual/exapp_development/faq/index.rst +++ b/developer_manual/exapp_development/faq/index.rst @@ -3,7 +3,7 @@ Frequently Asked Questions This section contains the most common or problematic questions that users or developers may encounter when working with AppAPI. -It can be used as pointer to another parts of the documentation, as it usually refers to, +It can be used as pointer to other parts of the documentation, as it usually refers to, or provide a brief answer. .. note:: diff --git a/developer_manual/exapp_development/tech_details/Authentication.rst b/developer_manual/exapp_development/tech_details/Authentication.rst index 1dc5c2f7d..faa6a709b 100644 --- a/developer_manual/exapp_development/tech_details/Authentication.rst +++ b/developer_manual/exapp_development/tech_details/Authentication.rst @@ -72,13 +72,13 @@ Authentication flow in details AppAPIAuth ^^^^^^^^^^ -AppAPI provides ``AppAPIAuth`` attribute with middleware to validate requests from ExApps. +AppAPI provides an ``AppAPIAuth`` attribute with middleware to validate requests from ExApps. In your API controllers, you can use it as a PHP attribute. AppAPI session keys ^^^^^^^^^^^^^^^^^^^ -After successful authentication, AppAPI sets `app_api` session key to ``true``. +After successful authentication, AppAPI sets the `app_api` session key to ``true``. .. code-block:: php diff --git a/developer_manual/exapp_development/tech_details/Deployment.rst b/developer_manual/exapp_development/tech_details/Deployment.rst index 21e6939d8..75cc959d5 100644 --- a/developer_manual/exapp_development/tech_details/Deployment.rst +++ b/developer_manual/exapp_development/tech_details/Deployment.rst @@ -16,9 +16,9 @@ The ExApp deployment process consists of 2 steps: DaemonConfig registration ------------------------- -The first step is to register DaemonConfig, where your ExApps will be deployed. -Before that, you will need to configure your Docker socket to be accessible by Nextcloud instance and webserver user. -If you use the remote Docker Engine API, you will need to expose it so it is accessible by Nextcloud instance and import certificates. +The first step is to register the DaemonConfig, where your ExApps will be deployed. +Before that, you will need to configure your Docker socket to be accessible by the Nextcloud instance and webserver user. +If you use the remote Docker Engine API, you will need to expose it so that it is accessible by the Nextcloud instance and import certificates. .. note:: For now, only the Docker daemon ``accepts-deploy-id: docker-install`` is supported. @@ -91,7 +91,7 @@ Manual install for development For development purposes, you can install the ExApp manually. There is a ``manual-install`` DeployConfig type, which can be used in case of development. -To register an ExApp with it, you need to provide the app info as a JSON string or a path to the app's XML file. +To register an ExApp with it, you need to provide the app info as a JSON string or a path to the app's info.xml file. For all examples and applications we release, we usually add the ``manual_install`` command in it's Makefile for easier development. @@ -105,15 +105,15 @@ For all examples and applications we release, we usually add the ``manual_instal .. _ex_app_env_vars: -Deploy env variables -******************** +Deploy environment variables +**************************** -Deploy env variables are used to configure the ExApp container. -The following env variables are required and built automatically: +Deploy environment variables are used to configure the ExApp container. +The following variables are required and built automatically: * ``AA_VERSION`` - AppAPI version * ``APP_SECRET`` - generated shared secret used for AppAPI authentication - * ``APP_ID`` - ExApp appid + * ``APP_ID`` - ExApp app ID * ``APP_DISPLAY_NAME`` - ExApp display name * ``APP_VERSION`` - ExApp version * ``APP_HOST`` - host ExApp is listening on @@ -124,11 +124,11 @@ The following env variables are required and built automatically: Application installation scheme ------------------------------- -1. AppAPI deploys the application and launches it. -2. AppAPI for `N` seconds (default ``90``) checks the ``/heartbeat`` endpoint with a ``GET`` request. -3. AppAPI sends a ``POST`` request to the ``/init`` endpoint. If the ExApp does not implement the ``/init`` endpoint and AppAPI receives a 501 or 404 status code, AppAPI enables the application and goes straight to step 5. -4. The ExApp sends an integer from ``0`` to ``100`` to the OCS endpoint ``apps/app_api/apps/status`` indicating the initialization progress. After sending ``100``, the application is considered initialized. -5. AppAPI sends a ``PUT`` request to the ``/enabled`` endpoint. + 1. AppAPI deploys the application and launches it. + 2. For `N` seconds (default ``90``), AppAPI checks the ``/heartbeat`` endpoint with a ``GET`` request. + 3. AppAPI sends a ``POST`` request to the ``/init`` endpoint. If the ExApp does not implement the ``/init`` endpoint and AppAPI receives a 501 or 404 status code, AppAPI enables the application and goes straight to step 5. + 4. The ExApp sends an integer from ``0`` to ``100`` to the OCS endpoint ``apps/app_api/apps/status`` indicating the initialization progress. After sending ``100``, the application is considered initialized. + 5. AppAPI sends a ``PUT`` request to the ``/enabled`` endpoint. ExApp info.xml schema --------------------- diff --git a/developer_manual/exapp_development/tech_details/InstallationFlow.rst b/developer_manual/exapp_development/tech_details/InstallationFlow.rst index 22e70f43c..7f4b6798a 100644 --- a/developer_manual/exapp_development/tech_details/InstallationFlow.rst +++ b/developer_manual/exapp_development/tech_details/InstallationFlow.rst @@ -20,7 +20,8 @@ The suffix will be added as follows: For ``cpu``, AppAPI will first try to get the image from ``ghcr.io/nextcloud/skeleton-cpu:latest``. In case the image is not found, ``ghcr.io/nextcloud/skeleton:latest`` will be pulled. -If you as an application developer want to have a custom images for any of these values, you can push the extended images to registry in addition to the base one. +If you as an application developer want to have a custom images for any of these values, +you can push the extended images to the registry in addition to the base one. Heartbeat --------- @@ -29,21 +30,21 @@ The first thing AppAPI does is deploy the application. In the case of Docker, this means: -1. performing an image pull -2. creating container from the docker image -3. if the container supports `healthcheck` - AppAPI waits for the `healthy` status -4. waiting until the “/heartbeat” endpoint becomes available with a ``GET`` request + 1. performing an image pull + 2. creating container from the docker image + 3. if the container supports `healthcheck` - AppAPI waits for the `healthy` status + 4. waiting until the “/heartbeat” endpoint becomes available with a ``GET`` request -The application, in response to the request "/heartbeat", should return json: ``{"status": "ok"}``. +The application, in response to the "/heartbeat" request, should return: ``{"status": "ok"}``. -.. note:: The request to ``/heartbeat`` endpoint is made without AppAPI authentication. +.. note:: The request to the ``/heartbeat`` endpoint is made without AppAPI authentication. Init ---- -.. note:: Starting from this point, all requests made by AppAPI contains :ref:`auth-headers`. +.. note:: Starting from this point, all requests made by AppAPI contain :ref:`authentication headers `. -After application is ready, which is determined by previous step, +After the application is ready, which is determined by the previous step, AppAPI sends a ``POST`` request to the ``/init`` application endpoint. *If the application does not need to carry out long initialization, it has an option to not implement "/init" endpoint, so @@ -51,8 +52,8 @@ AppAPI will get 404 or 501 error on it's request, but you can consider that init In case you want to implement "/init" endpoint, your application should: -1. In "/init" handler: return a Response with empty JSON data on AppAPI call. -2. In background job: send an OCS request to ``PUT /ocs/v1.php/apps/app_api/ex-app/status`` with the progress value. + 1. In "/init" handler: return a Response with empty JSON data on AppAPI call. + 2. In background job: send an OCS request to ``PUT /ocs/v1.php/apps/app_api/ex-app/status`` with the progress value. .. warning:: @@ -61,21 +62,19 @@ In case you want to implement "/init" endpoint, your application should: Possible values for **progress** are integers from 1 to 100; after receiving the value 100, the **application is considered initialized and ready to work**. -If at the initialization stage the application has a critical error due to which its further operation is impossible, - +If, at the initialization stage, the application has a critical error due to which its further operation is impossible, ``"error": "some error"`` - should be added to the ``OCS request`` for setting progress, with a short explanation at what stage this error occurred. -Example of request payload with error will look like this:: +Example of request payload with error:: {"progress": 67, "error": "connection error to huggingface."} Enabled ------- -After receiving **progress: 100** (*or when ExApp is not implementing the "/init" endpoint*), AppAPI enables the application. +After receiving **progress: 100** (*or when the ExApp is not implementing the "/init" endpoint*), AppAPI enables the application. To enable or disable the application, a PUT request is sent to the ``/enabled`` endpoint. @@ -83,16 +82,16 @@ To enable or disable the application, a PUT request is sent to the ``/enabled`` The ``enabled`` parameter accepts an integer value: -* `1` to enable the application -* `0` to disable the application + * `1` to enable the application + * `0` to disable the application For example, to enable the application, the request would be:: - PUT http://expapp:2432/enabled?enabled=1 + PUT http://ex-app:2432/enabled?enabled=1 Similarly, to disable the application, the request would be:: - PUT http://expapp:2432/enabled?enabled=0 + PUT http://ex-app:2432/enabled?enabled=0 This approach ensures that the application's state can be easily toggled using a simple query parameter. @@ -109,4 +108,4 @@ for success, and if some error occurs during **enabling**, it should be present {"error": "i can't handle enabling"} -This is all three steps involved in the ExApp installation flow. +This is all the steps involved in the ExApp installation flow. diff --git a/developer_manual/exapp_development/tech_details/Translations.rst b/developer_manual/exapp_development/tech_details/Translations.rst index 7d5806823..ce5eeea8e 100644 --- a/developer_manual/exapp_development/tech_details/Translations.rst +++ b/developer_manual/exapp_development/tech_details/Translations.rst @@ -1,16 +1,15 @@ Translations ============ -ExApps translations work in the `same way as for PHP apps `_ with a few adjustments -and differences. +ExApps translations work in the :doc:`same way as for PHP apps <../../basics/front-end/l10n>` with a few adjustments and differences. -In short, you just have to provide a ``l10n/.js`` (for front-end) and ``l10n/.json`` (for back-end) files for your app. +In short, you just have to provide the ``l10n/.js`` (for front-end) and ``l10n/.json`` (for back-end) files for your app. Front-end ********* -For the front-end part AppAPI will inject the current user's locale ``l10n/.js`` script, so that access to translated strings in kept the same as was before in PHP apps. +For the front-end part, AppAPI will inject the current user's locale ``l10n/.js`` script, so that access to translated strings in kept the same as was before in PHP apps. .. note:: @@ -20,31 +19,32 @@ For the front-end part AppAPI will inject the current user's locale ``l10n/`_. Manual install ************** -For ``manual-install`` type administrator will have to manually extract to the server's `writable apps directory `_ ``l10n`` folder of ExApp +For the ``manual-install`` type, an administrator will have to manually extract to the server's `writable apps directory `_ ``l10n`` folder of the ExApp (e.g. ``/path/to/apps-writable//l10n/*.(js|json)``). -This will allow server to access ExApp's strings with translations. +This will allow the server to access the ExApp's strings with translations. .. note:: - Only ``l10n`` folder must be present on the server side, ``appinfo/info.xml`` could lead to be misdetected by server as PHP app folder. + Only the ``l10n`` folder must be present on the server side; ``appinfo/info.xml`` could lead to misdetection by the server as a PHP app folder. Docker install ************** -For ``docker-install`` type AppAPI will extract ``l10n`` folder to the server automatically during installation from ExApp release archive. +For the ``docker-install`` type, AppAPI will extract the ``l10n`` folder to the server automatically during installation from the ExApp release archive. Translation tool **************** -To add support for your language in Nextcloud `translationtool `_ feel free to create an issue in the `nextcloud/docker-ci `_ repository -or open a pull request with the changes made in ``createPotFile`` function to extract and convert translation strings. +To add support for your language in Nextcloud `translationtool `_, +feel free to create an issue in the `nextcloud/docker-ci `_ repository +or open a pull request with the changes made in the ``createPotFile`` function to extract and convert translation strings. diff --git a/developer_manual/exapp_development/tech_details/api/appconfig.rst b/developer_manual/exapp_development/tech_details/api/appconfig.rst index 5e8e83568..af112279a 100644 --- a/developer_manual/exapp_development/tech_details/api/appconfig.rst +++ b/developer_manual/exapp_development/tech_details/api/appconfig.rst @@ -2,7 +2,7 @@ AppConfig ========= -ExApp AppConfig API is similar to the standard Nextcloud **appconfig** API. +The ExApp AppConfig API is similar to the standard Nextcloud **appconfig** API. Set app config value ^^^^^^^^^^^^^^^^^^^^ @@ -28,7 +28,7 @@ Response data ************* On success, ExAppConfig object is returned. -On error OCS Bad Request is returned. +On error, OCS Bad Request is returned. .. code-block:: json diff --git a/developer_manual/exapp_development/tech_details/api/events_listener.rst b/developer_manual/exapp_development/tech_details/api/events_listener.rst index 042cc72f3..77e562a3c 100644 --- a/developer_manual/exapp_development/tech_details/api/events_listener.rst +++ b/developer_manual/exapp_development/tech_details/api/events_listener.rst @@ -4,16 +4,16 @@ Events Listener =============== -This API allows you to listen to `Nextcloud events `_ +This API allows you to listen to :doc:`Nextcloud events <../../../basics/events>`. -Currently only **limited** numbers of events are supported. +Currently only a **limited** number of events are supported. Please let us know if there are any specific event we should add support to. .. note:: - Unlike PHP events, all information from events comes to ExApp **asynchronously**, more like a notification system - to no slow down the server. + Unlike PHP events, all information from events comes to the ExApp **asynchronously**, more like a notification system + in order to not slow down the server. Register ^^^^^^^^ @@ -43,7 +43,7 @@ OCS endpoint: ``DELETE /apps/app_api/api/v1/events_listener`` Params ****** -To unregister EventsListener, you just need to provide an `eventType` of the registered EventsListener: +To unregister EventsListener, you just need to provide an `eventType` for the registered EventsListener: .. code-block:: json @@ -78,6 +78,6 @@ Supported event sub-types: * ``NodeRenamedEvent`` * ``NodeCopiedEvent`` -For all Node events ``event_data`` contain key **target** which has the same format like in :ref:`FileActionsMenu payload ` +For all Node events, ``event_data`` contains a ``target`` key which has the same format as in :ref:`FileActionsMenu payload `. -For ``NodeCopiedEvent`` and ``NodeRenamedEvent`` there is also a ``source`` key in the same format. +For ``NodeCopiedEvent`` and ``NodeRenamedEvent``, there is also a ``source`` key in the same format. diff --git a/developer_manual/exapp_development/tech_details/api/exapp.rst b/developer_manual/exapp_development/tech_details/api/exapp.rst index 63fc41d6c..83bc8275c 100644 --- a/developer_manual/exapp_development/tech_details/api/exapp.rst +++ b/developer_manual/exapp_development/tech_details/api/exapp.rst @@ -56,12 +56,12 @@ Request data Response data ************* -Returns HTTP 200 on success, HTTP 404 - on error. +Returns HTTP 200 on success, HTTP 404 on error. Get Nextcloud URL ^^^^^^^^^^^^^^^^^ -It might be necessary for ExApp to know (or update) the Nextcloud URL. +It might be necessary for the ExApp to know (or update) the Nextcloud URL. OCS endpoint: ``GET /apps/app_api/api/v1/info/nextcloud_url`` @@ -130,7 +130,7 @@ OCS endpoint: ``GET /apps/app_api/api/v1/ex-app/state`` .. note:: This endpoint can be called by ExApp even if it is disabled on the Nextcloud side, - and requires :ref:`AppAPIAuth `. + and requires :doc:`AppAPIAuth <../Authentication>`. Response data ************* diff --git a/developer_manual/exapp_development/tech_details/api/fileactionsmenu.rst b/developer_manual/exapp_development/tech_details/api/fileactionsmenu.rst index 9c9b98c69..07a885618 100644 --- a/developer_manual/exapp_development/tech_details/api/fileactionsmenu.rst +++ b/developer_manual/exapp_development/tech_details/api/fileactionsmenu.rst @@ -5,11 +5,11 @@ File Actions Menu ================= FileActionsMenu is a simple API for registering entry to the file actions menu for ExApps. -AppAPI takes responsibility to register FileActionsMenu, ExApps needs only to register it in AppAPI. +AppAPI takes responsibility to register FileActionsMenu; ExApps only need to register it in AppAPI. .. note:: - FileActionsMenu rendered only for enabled ExApps. + The FileActionsMenu is rendered only for enabled ExApps. Register ^^^^^^^^ @@ -51,7 +51,7 @@ OCS endpoint: ``DELETE /apps/app_api/api/v1/ui/files-actions-menu`` Params ****** -To unregister FileActionsMenu, you just need to provide name of registered FileActionsMenu: +To unregister FileActionsMenu, you just need to provide the name of the registered FileActionsMenu: .. code-block:: json @@ -64,8 +64,8 @@ To unregister FileActionsMenu, you just need to provide name of registered FileA Action payload to ExApp ^^^^^^^^^^^^^^^^^^^^^^^ -When FileActionsMenu invoked, AppAPI forwards action for handling to ExApp. -The following data is sent to ExApp FileActionsMenu handler from the context of action: +When FileActionsMenu is invoked, AppAPI forwards the handling action to the ExApp. +The following data is sent to the ExApp FileActionsMenu handler from the context of the action: .. code-block:: json @@ -95,24 +95,24 @@ Redirect to ExApp UI page (top menu) .. note:: Supported only for Nextcloud 28+. -If you want to open some files in ExApp UI, your FileActionsMenu have to be registered using OCS v2 version (``/apps/app_api/api/v2/ui/files-actions-menu``). +If you want to open some files in the ExApp UI, your FileActionsMenu has to be registered using OCS v2 version (``/apps/app_api/api/v2/ui/files-actions-menu``). After that, AppAPI will expect in the JSON response of the ExApp ``action_handler`` the ``redirect_handler`` - a relative path on the ExApp Top Menu page, -to which AppAPI will attach a ``fileIds`` query parameter with the selected file ids, for example: +to which AppAPI will attach a ``fileIds`` query parameter with the selected file IDs, for example: ``/index.php/apps/app_api/embedded/ui_example/first_menu/second_page?fileIds=123,124,125``, where the ``first_menu`` is the name of the Top Menu ExApp UI page, -and the ``second_page`` relative route handled on the frontend routing of the ExApp, -the ``fileIds`` query parameter contains the selected file ids separated by commas. -After that you can get the files info via webdav search request, see `ui_example `_. +and the ``second_page`` the relative route handled on the frontend routing of the ExApp. +the ``fileIds`` query parameter contains the selected file IDs separated by commas. +After that, you can get the files info via WebDAV search request, see `ui_example `_. Request flow ^^^^^^^^^^^^ -General workflow of ExApp based on FileActionsMenu. +General ExApp workflow based on FileActionsMenu. User action *********** @@ -130,8 +130,8 @@ User action Action results ************** -File processing results could be stored next to initial file or anywhere else, -e.g. on configured location in ExApp settings (``appconfig_ex``) or ExApp user settings (``preferences_ex``). +File processing results could be stored next to the initial file or anywhere else, +e.g. on a location configured in ExApp settings (``appconfig_ex``) or ExApp user settings (``preferences_ex``). .. mermaid:: @@ -144,5 +144,5 @@ Examples Here is a list of simple example ExApps based on FileActionsMenu: -* `to_gif `_ - ExApp based on FileActionsMenu to convert videos to gif in place +* `to_gif `_ - ExApp based on FileActionsMenu to convert videos to GIF in place * `upscaler_example `_ - ExApp based on FileActionsMenu to upscale image in place diff --git a/developer_manual/exapp_development/tech_details/api/logging.rst b/developer_manual/exapp_development/tech_details/api/logging.rst index 623422bcc..ad8aa31d3 100644 --- a/developer_manual/exapp_development/tech_details/api/logging.rst +++ b/developer_manual/exapp_development/tech_details/api/logging.rst @@ -6,8 +6,8 @@ There is a logging API that can be used to log messages from ExApps in Nextcloud .. note:: - You can retrieve Nextcloud `loglevel` for internal ExApp usage - from private `app_api` (after authentication) capabilities + You can retrieve the Nextcloud `loglevel` for internal ExApp usage + from private `app_api` (after authentication) capabilities. Send log message (OCS) ^^^^^^^^^^^^^^^^^^^^^^ @@ -25,11 +25,11 @@ Request data } -The possible value of ``log_lvl`` is described here: `Nextcloud Log level `_ +The possible values of ``log_lvl`` are described here: `Nextcloud Log level `_ Response data ************* -If no error occurs, empty response with result code 200 is returned. -If ExApp is not found or disable, or the loglevel is invalid - OCS Bad Request is returned. +If no error occurs, an empty response with status code 200 is returned. +If the ExApp is not found or disabled, or the `loglevel` is invalid, an OCS Bad Request is returned. diff --git a/developer_manual/exapp_development/tech_details/api/notifications.rst b/developer_manual/exapp_development/tech_details/api/notifications.rst index cde06b487..0d9f80bfb 100644 --- a/developer_manual/exapp_development/tech_details/api/notifications.rst +++ b/developer_manual/exapp_development/tech_details/api/notifications.rst @@ -3,8 +3,8 @@ Notifications ============= AppAPI allows ExApps to send limited notifications to users. -ExApp can send simple notification using available `rich object strings `_. -More info about rich objects string can be found `here `_. +The ExApp can send simple notifications using available `rich object strings `_. +More info about rich object strings can be found `here `_. Send notification (OCS) ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/developer_manual/exapp_development/tech_details/api/occ_command.rst b/developer_manual/exapp_development/tech_details/api/occ_command.rst index 46e09cb59..2e09fa33b 100644 --- a/developer_manual/exapp_development/tech_details/api/occ_command.rst +++ b/developer_manual/exapp_development/tech_details/api/occ_command.rst @@ -4,9 +4,9 @@ OCC Command =========== -This API allows you to register the occ (CLI) commands. -The principal is similar to the regular Nextcloud OCC command for PHP apps, that are working in context of the Nextcloud instance, -but for ExApps it is a trigger via Nextcloud OCC interface to perform some action on the External App side. +This API allows you to register OCC CLI commands. +The principle is similar to the regular occ command for PHP apps that are working within the context of the Nextcloud instance, +but for ExApps, it is a trigger via the Nextcloud OCC interface to perform some action on the ExApp side. .. note:: @@ -59,7 +59,7 @@ see the original docs for the Symfony console input parameters, which are actual Example ******* -Lets assume we have a command `ping` that takes an argument `test_arg` and has an option `test-option`: +Let's assume we have a command `ping` that takes an argument `test_arg` and has an option `test-option`: .. code-block:: json @@ -99,7 +99,7 @@ OCS endpoint: ``DELETE /apps/app_api/api/v1/occ_command`` Params ****** -To unregister OCC Command, you just need to provide a command `name`: +To unregister an OCC CLI command, you just need to provide a command `name`: .. code-block:: json diff --git a/developer_manual/exapp_development/tech_details/api/preferences.rst b/developer_manual/exapp_development/tech_details/api/preferences.rst index d7b36faf6..b17a5114a 100644 --- a/developer_manual/exapp_development/tech_details/api/preferences.rst +++ b/developer_manual/exapp_development/tech_details/api/preferences.rst @@ -2,14 +2,14 @@ Preferences =========== -ExApp preferences API is similar to the standard preferences API. -It's a user specific settings. +The ExApp preferences API is similar to the standard preferences API. +It is a user specific setting. Set user config value ^^^^^^^^^^^^^^^^^^^^^ -Set or update config value for **current authenticated user**. +Set or update config value for the **current authenticated user**. OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/preference`` @@ -26,8 +26,8 @@ Request data Response data ************* -On success ExAppPreference object is returned. -On error OCS Bad Request is returned. +On success, ExAppPreference object is returned. +On error, OCS Bad Request is returned. .. code-block:: json @@ -56,7 +56,7 @@ On error OCS Bad Request is returned. Get user config values ^^^^^^^^^^^^^^^^^^^^^^ -Get config values for **current authenticated user**. +Get config values for the **current authenticated user**. OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/preference/get-values`` @@ -104,7 +104,7 @@ List of ExApp preferences values are returned. Delete user config values ^^^^^^^^^^^^^^^^^^^^^^^^^ -Delete config values for **current authenticated user**. +Delete config values for the **current authenticated user**. OCS endpoint: ``DELETE /apps/app_api/api/v1/ex-app/preference`` diff --git a/developer_manual/exapp_development/tech_details/api/routes.rst b/developer_manual/exapp_development/tech_details/api/routes.rst index 5f8b406ce..b8739088b 100644 --- a/developer_manual/exapp_development/tech_details/api/routes.rst +++ b/developer_manual/exapp_development/tech_details/api/routes.rst @@ -37,8 +37,8 @@ where the fields are: - ``url``: the route to be registered on the ExApp side, can be a regex - ``verb``: the HTTP verb that the route will accept, can be a comma separated list of verbs - ``access_level``: the name of the access level required to access the route, PUBLIC - public access without auth, USER - Nextcloud user auth required, ADMIN - admin user required -- ``headers_to_exclude``: a json encoded string of an array of strings, the headers that the ExApp wants to be excluded from the request to it -- ``bruteforce_protection``: a json encoded string of an array of numbers, the HTTP status codes that must trigger the bruteforce protection +- ``headers_to_exclude``: a JSON-encoded string of an array of strings, the headers that the ExApp wants to be excluded from the request to it +- ``bruteforce_protection``: a JSON-encoded string of an array of numbers, the HTTP status codes that must trigger the bruteforce protection Unregister diff --git a/developer_manual/exapp_development/tech_details/api/settings.rst b/developer_manual/exapp_development/tech_details/api/settings.rst index 02341da2d..b08edf0e1 100644 --- a/developer_manual/exapp_development/tech_details/api/settings.rst +++ b/developer_manual/exapp_development/tech_details/api/settings.rst @@ -4,19 +4,19 @@ Declarative Settings ==================== -Starting from Nextcloud **29**, AppAPI provides the ability to display ex-application settings. -When admin or user changes some ex-app settings -they will be stored in the database and can be received using :doc:`preferences` or :doc:`appconfig` API. +Starting from Nextcloud **29**, AppAPI provides the ability to display ExApp settings. +When an admin or user changes some ExApp settings, +they will be stored in the database and can be retrieved using :doc:`preferences` or :doc:`appconfig` API. .. note:: - Settings rendered only for enabled ExApps. + These settings are rendered only for enabled ExApps. .. warning:: ``section_id`` from **scheme** should be already registered by any PHP application. - **AppAPI** provides two sections for that: ``ai_integration_team`` and ``declarative_settings``, you can use them. + **AppAPI** provides two sections which you can use for that: ``ai_integration_team`` and ``declarative_settings``. Register Settings ^^^^^^^^^^^^^^^^^ @@ -162,7 +162,7 @@ Example of settings scheme in Python: }, { 'id': 'test_ex_app_field_5', - 'title': 'Multiple checkbox toggles, describing one setting, checked options are saved as an JSON object {foo: true, bar: false}', + 'title': 'Multiple checkbox toggles, describing one setting, checked options are saved as a JSON object {foo: true, bar: false}', 'description': 'Select checkbox option setting', 'type': 'multi-checkbox', 'default': {'foo': True, 'bar': True}, diff --git a/developer_manual/exapp_development/tech_details/api/talkbots.rst b/developer_manual/exapp_development/tech_details/api/talkbots.rst index c6825629d..12fe74c07 100644 --- a/developer_manual/exapp_development/tech_details/api/talkbots.rst +++ b/developer_manual/exapp_development/tech_details/api/talkbots.rst @@ -2,8 +2,8 @@ Talk bots ========= -AppAPI provides API for registering ExApps Talk bots. -This means that ExApps could be just as Talk bot or it could be as one of the options of the app. +AppAPI provides an API for registering ExApp Talk bots. +This means that ExApps could function as just a Talk bot or as one of the app options. Read more about Talk bots `here `_. Register ExApp Talk bot (OCS) @@ -26,7 +26,7 @@ Request data Unregister ExApp Talk bot (OCS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To unregister the ExApp Talk bot, you will have to pass the route where the Talk bot is registered. +To unregister the ExApp Talk bot, pass the route where the Talk bot is registered. OCS endpoint: ``DELETE /apps/app_api/api/v1/talk_bot`` diff --git a/developer_manual/exapp_development/tech_details/api/topmenu.rst b/developer_manual/exapp_development/tech_details/api/topmenu.rst index 22e572e1e..624314797 100644 --- a/developer_manual/exapp_development/tech_details/api/topmenu.rst +++ b/developer_manual/exapp_development/tech_details/api/topmenu.rst @@ -5,11 +5,11 @@ Top Menu Entry ============== TopMenu is an API for registering entry in the Nextcloud Top Menu for ExApps. -AppAPI takes responsibility to register TopMenu and proxy all requests to ExApp. +AppAPI takes responsibility to register TopMenu and proxy all requests to the ExApp. .. note:: - TopMenu rendered only for enabled ExApps. + The TopMenu is rendered only for enabled ExApps. Register Menu Entry ^^^^^^^^^^^^^^^^^^^ @@ -30,14 +30,14 @@ Complete list of params (including optional): "adminRequired": "0 or 1", } -.. note:: ``icon`` are relative to the ExApp root, starting slash is not required. +.. note:: ``icon`` is relative to the ExApp root, starting slash is not required. Optional params *************** * `icon` - Url to icon, default: **null** - * `adminRequired` - Value indicating should be Entry visible to all or only to admins. + * `adminRequired` - Value indicating whether the entry should be visible to all or only to admins Unregister Menu Entry ^^^^^^^^^^^^^^^^^^^^^ @@ -47,7 +47,7 @@ OCS endpoint: ``DELETE /apps/app_api/api/v1/ui/top-menu`` Params ****** -To unregister TopMenu, you just need to provide name of registered TopMenu: +To unregister TopMenu, just provide the name of registered TopMenu: .. code-block:: json