From e3989934a2c537b0a6e7c556c9163332bd973e79 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Wed, 29 Jan 2025 13:56:02 +0100
Subject: [PATCH 01/23] First create some structure to fill in the content in
 next commits

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 66 ++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 34bb1ddc314..3ec00021972 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -339,7 +339,71 @@ Cookies can be set or modified directly on the response class:
 Responses
 ---------
 
-Similar to how every controller receives a request object, every controller method has to return a Response. This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder.
+Similar to how every controller receives a request object, every controller method has to return a Response.
+This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder.
+
+.. _controller_html_responses:
+
+HTML-based Responses
+--------------------
+
+Templates
+^^^^^^^^^
+
+Public page templates
+^^^^^^^^^^^^^^^^^^^^^
+
+
+Data-based responses
+--------------------
+
+OCS
+^^^
+
+JSON
+^^^^
+
+Handling errors
+^^^^^^^^^^^^^^^
+
+Responders
+^^^^^^^^^^
+
+Miscellaneous responses
+-----------------------
+
+Redirects
+^^^^^^^^^
+
+Downloads
+^^^^^^^^^
+
+Creating custom responses
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Streamed and lazily rendered responses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Security considerations
+-----------------------
+
+Authentication
+^^^^^^^^^^^^^^
+
+Loosening the default restrictions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rate limiting
+^^^^^^^^^^^^^
+
+Brute-force protection
+^^^^^^^^^^^^^^^^^^^^^^
+
+Modifying the content security policy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+---
 
 JSON
 ^^^^

From 2f1bc359c41da82bb5f19a4709134299ed2835b1 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 13:02:53 +0100
Subject: [PATCH 02/23] Move section html templates

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 69 ++++++++++++-------------
 1 file changed, 34 insertions(+), 35 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 3ec00021972..c6654be9dd2 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -347,9 +347,43 @@ This can be in the form of a Response subclass or in the form of a value that ca
 HTML-based Responses
 --------------------
 
+.. _controller_template:
+
 Templates
 ^^^^^^^^^
 
+A :doc:`template <front-end/templates>` can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters:
+
+* **appName**: tells the template engine in which app the template should be located
+* **templateName**: the name of the template inside the templates/ folder without the .php extension
+* **parameters**: optional array parameters that are available in the template through $_, e.g.::
+
+    array('key' => 'something')
+
+  can be accessed through::
+
+    $_['key']
+
+* **renderAs**: defaults to *user*, tells Nextcloud if it should include it in the web interface, or in case *blank* is passed solely render the template
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\TemplateResponse;
+
+    class PageController extends Controller {
+
+        public function index(): TemplateResponse {
+            $templateName = 'main';  // will use templates/main.php
+            $parameters = array('key' => 'hi');
+            return new TemplateResponse($this->appName, $templateName, $parameters);
+        }
+
+    }
+
 Public page templates
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -532,41 +566,6 @@ Because returning values works fine in case of a success but not in case of fail
     }
 
 
-Templates
-^^^^^^^^^
-
-A :doc:`template <front-end/templates>` can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters:
-
-* **appName**: tells the template engine in which app the template should be located
-* **templateName**: the name of the template inside the templates/ folder without the .php extension
-* **parameters**: optional array parameters that are available in the template through $_, e.g.::
-
-    array('key' => 'something')
-
-  can be accessed through::
-
-    $_['key']
-
-* **renderAs**: defaults to *user*, tells Nextcloud if it should include it in the web interface, or in case *blank* is passed solely render the template
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\TemplateResponse;
-
-    class PageController extends Controller {
-
-        public function index(): TemplateResponse {
-            $templateName = 'main';  // will use templates/main.php
-            $parameters = array('key' => 'hi');
-            return new TemplateResponse($this->appName, $templateName, $parameters);
-        }
-
-    }
-
 Public page templates
 ^^^^^^^^^^^^^^^^^^^^^
 

From 9e95840608dd415ff8343b888bb017ab2d64e120 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 13:04:51 +0100
Subject: [PATCH 03/23] Moved section public html templates

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 79 ++++++++++++-------------
 1 file changed, 37 insertions(+), 42 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index c6654be9dd2..0a6eecca147 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -387,6 +387,43 @@ A :doc:`template <front-end/templates>` can be rendered by returning a TemplateR
 Public page templates
 ^^^^^^^^^^^^^^^^^^^^^
 
+For public pages, that are rendered to users who are not logged in to the
+Nextcloud instance, a ``OCP\\AppFramework\\Http\\Template\\PublicTemplateResponse`` should be used, to load the
+correct base template. It also allows adding an optional set of actions that
+will be shown in the top right corner of the public page.
+
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\Template\SimpleMenuAction;
+    use OCP\AppFramework\Http\Template\PublicTemplateResponse;
+
+    class PageController extends Controller {
+
+        public function index(): PublicTemplateResponse {
+            $template = new PublicTemplateResponse($this->appName, 'main', []);
+            $template->setHeaderTitle('Public page');
+            $template->setHeaderDetails('some details');
+            $template->setHeaderActions([
+                new SimpleMenuAction('download', 'Label 1', 'icon-css-class1', 'link-url', 0),
+                new SimpleMenuAction('share', 'Label 2', 'icon-css-class2', 'link-url', 10),
+            ]);
+            return $template;
+        }
+
+    }
+
+The header title and subtitle will be rendered in the header, next to the logo.
+The action with the highest priority (lowest number) will be used as the
+primary action, others will shown in the popover menu on demand.
+
+A ``OCP\\AppFramework\\Http\\Template\\SimpleMenuAction`` will be a link with an icon added to the menu. App
+developers can implement their own types of menu renderings by adding a custom
+class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interface.
 
 Data-based responses
 --------------------
@@ -566,48 +603,6 @@ Because returning values works fine in case of a success but not in case of fail
     }
 
 
-Public page templates
-^^^^^^^^^^^^^^^^^^^^^
-
-For public pages, that are rendered to users who are not logged in to the
-Nextcloud instance, a ``OCP\\AppFramework\\Http\\Template\\PublicTemplateResponse`` should be used, to load the
-correct base template. It also allows adding an optional set of actions that
-will be shown in the top right corner of the public page.
-
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\Template\SimpleMenuAction;
-    use OCP\AppFramework\Http\Template\PublicTemplateResponse;
-
-    class PageController extends Controller {
-
-        public function index(): PublicTemplateResponse {
-            $template = new PublicTemplateResponse($this->appName, 'main', []);
-            $template->setHeaderTitle('Public page');
-            $template->setHeaderDetails('some details');
-            $template->setHeaderActions([
-                new SimpleMenuAction('download', 'Label 1', 'icon-css-class1', 'link-url', 0),
-                new SimpleMenuAction('share', 'Label 2', 'icon-css-class2', 'link-url', 10),
-            ]);
-            return $template;
-        }
-
-    }
-
-The header title and subtitle will be rendered in the header, next to the logo.
-The action with the highest priority (lowest number) will be used as the
-primary action, others will shown in the popover menu on demand.
-
-A ``OCP\\AppFramework\\Http\\Template\\SimpleMenuAction`` will be a link with an icon added to the menu. App
-developers can implement their own types of menu renderings by adding a custom
-class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interface.
-
-
 
 Redirects
 ^^^^^^^^^

From af0cad8bf47f9a99cdd960ec48fe477917b429a7 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 13:26:49 +0100
Subject: [PATCH 04/23] Move section OCS

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 98 ++++++++++++-------------
 1 file changed, 48 insertions(+), 50 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 0a6eecca147..ad133f55db1 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -428,9 +428,57 @@ class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interf
 Data-based responses
 --------------------
 
+.. _ocscontroller:
+
 OCS
 ^^^
 
+.. note::
+    This is purely for compatibility reasons. If you are planning to offer an external API, go for a :ref:`REST APIs <rest-apis>` instead.
+
+In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added.
+To migrate your API you can use the **OCP\\AppFramework\\OCSController** base class and return your data in the form of a DataResponse in the following way:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Http\DataResponse;
+    use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+    use OCP\AppFramework\OCSController;
+
+    class ShareController extends OCSController {
+
+        #[NoAdminRequired]
+        public function getShares(): DataResponse {
+            return new DataResponse([
+                //Your data here
+            ]);
+        }
+
+    }
+
+The format parameter works out of the box, no intervention is required.
+
+In order to make routing work for OCS routes you need to add a separate ‘ocs’ entry to the routing table of your app. Inside these are normal routes.
+
+.. code-block:: php
+
+   <?php
+
+   return [
+        'ocs' => [
+            [
+                'name' => 'Share#getShares',
+                'url' => '/api/v1/shares',
+                'verb' => 'GET',
+            ],
+        ],
+   ];
+
+Now your method will be reachable via ``<server>/ocs/v2.php/apps/<APPNAME>/api/v1/shares``
+
 JSON
 ^^^^
 
@@ -785,56 +833,6 @@ The following policy for instance allows images, audio and videos from other dom
 
     }
 
-.. _ocscontroller:
-
-OCS
-^^^
-
-.. note:: This is purely for compatibility reasons. If you are planning to offer an external API, go for a :doc:`../digging_deeper/rest_apis` instead.
-
-In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added. To migrate your API you can use the **OCP\\AppFramework\\OCSController** base class and return your data in the form of a DataResponse in the following way:
-
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Http\DataResponse;
-    use OCP\AppFramework\Http\Attribute\NoAdminRequired;
-    use OCP\AppFramework\OCSController;
-
-    class ShareController extends OCSController {
-
-        #[NoAdminRequired]
-        public function getShares(): DataResponse {
-            return new DataResponse([
-                //Your data here
-            ]);
-        }
-
-    }
-
-The format parameter works out of the box, no intervention is required.
-
-In order to make routing work for OCS routes you need to add a separate 'ocs' entry to the routing table of your app.
-Inside these are normal routes.
-
-.. code-block:: php
-
-   <?php
-
-   return [
-        'ocs' => [
-            [
-                'name' => 'Share#getShares',
-                'url' => '/api/v1/shares',
-                'verb' => 'GET',
-            ],
-        ],
-   ];
-
-Now your method will be reachable via ``<server>/ocs/v2.php/apps/<APPNAME>/api/v1/shares``
 
 Handling errors
 ^^^^^^^^^^^^^^^

From 578cbcef439f95afacedd65183778f61cf7f1ee2 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 15:21:41 +0100
Subject: [PATCH 05/23] Move section JSON

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 79 ++++++++++++-------------
 1 file changed, 38 insertions(+), 41 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index ad133f55db1..fcecdabb85e 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -482,6 +482,44 @@ Now your method will be reachable via ``<server>/ocs/v2.php/apps/<APPNAME>/api/v
 JSON
 ^^^^
 
+Returning JSON is simple, just pass an array to a JSONResponse:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\JSONResponse;
+
+    class PageController extends Controller {
+
+        public function returnJSON(): JSONResponse {
+            $params = array('test' => 'hi');
+            return new JSONResponse($params);
+        }
+
+    }
+
+Because returning JSON is such a common task, there's even a shorter way to do this:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+
+    class PageController extends Controller {
+
+        public function returnJSON(): array {
+            return array('test' => 'hi');
+        }
+
+    }
+
+Why does this work? Because the dispatcher sees that the controller did not return a subclass of a Response and asks the controller to turn the value into a Response. That's where responders come in.
+
 Handling errors
 ^^^^^^^^^^^^^^^
 
@@ -524,47 +562,6 @@ Modifying the content security policy
 
 ---
 
-JSON
-^^^^
-
-Returning JSON is simple, just pass an array to a JSONResponse:
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\JSONResponse;
-
-    class PageController extends Controller {
-
-        public function returnJSON(): JSONResponse {
-            $params = array('test' => 'hi');
-            return new JSONResponse($params);
-        }
-
-    }
-
-Because returning JSON is such a common task, there's even a shorter way to do this:
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-
-    class PageController extends Controller {
-
-        public function returnJSON(): array {
-            return array('test' => 'hi');
-        }
-
-    }
-
-Why does this work? Because the dispatcher sees that the controller did not return a subclass of a Response and asks the controller to turn the value into a Response. That's where responders come in.
-
 Responders
 ^^^^^^^^^^
 

From e58d1ff44ee00bcb4ec2c4a673aeead6624631f1 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 15:23:19 +0100
Subject: [PATCH 06/23] Move section Responders

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 73 ++++++++++++-------------
 1 file changed, 35 insertions(+), 38 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index fcecdabb85e..e46bb14dd49 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -523,44 +523,7 @@ Why does this work? Because the dispatcher sees that the controller did not retu
 Handling errors
 ^^^^^^^^^^^^^^^
 
-Responders
-^^^^^^^^^^
-
-Miscellaneous responses
------------------------
-
-Redirects
-^^^^^^^^^
-
-Downloads
-^^^^^^^^^
-
-Creating custom responses
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Streamed and lazily rendered responses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Security considerations
------------------------
-
-Authentication
-^^^^^^^^^^^^^^
-
-Loosening the default restrictions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Rate limiting
-^^^^^^^^^^^^^
-
-Brute-force protection
-^^^^^^^^^^^^^^^^^^^^^^
-
-Modifying the content security policy
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
----
+.. _controller-responders:
 
 Responders
 ^^^^^^^^^^
@@ -647,7 +610,41 @@ Because returning values works fine in case of a success but not in case of fail
 
     }
 
+Miscellaneous responses
+-----------------------
+
+Redirects
+^^^^^^^^^
+
+Downloads
+^^^^^^^^^
+
+Creating custom responses
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Streamed and lazily rendered responses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Security considerations
+-----------------------
+
+Authentication
+^^^^^^^^^^^^^^
+
+Loosening the default restrictions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rate limiting
+^^^^^^^^^^^^^
+
+Brute-force protection
+^^^^^^^^^^^^^^^^^^^^^^
 
+Modifying the content security policy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+---
 
 Redirects
 ^^^^^^^^^

From 1693e6ef10a7ca0439a37d26427dd9b951d89bac Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 13:29:15 +0100
Subject: [PATCH 07/23] Moving section handling errors

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 51 ++++++++++++-------------
 1 file changed, 25 insertions(+), 26 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index e46bb14dd49..022631d5bfb 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -523,6 +523,31 @@ Why does this work? Because the dispatcher sees that the controller did not retu
 Handling errors
 ^^^^^^^^^^^^^^^
 
+Sometimes a request should fail, for instance if an author with id 1 is requested but does not exist. In that case use an appropriate `HTTP error code <https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error>`_ to signal the client that an error occurred.
+
+Each response subclass has access to the **setStatus** method which lets you set an HTTP status code. To return a JSONResponse signaling that the author with id 1 has not been found, use the following code:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http;
+    use OCP\AppFramework\Http\JSONResponse;
+
+    class AuthorController extends Controller {
+
+        public function show($id) {
+            try {
+                // try to get author with $id
+
+            } catch (NotFoundException $ex) {
+                return new JSONResponse(array(), Http::STATUS_NOT_FOUND);
+            }
+        }
+    }
+
 .. _controller-responders:
 
 Responders
@@ -828,33 +853,7 @@ The following policy for instance allows images, audio and videos from other dom
     }
 
 
-Handling errors
-^^^^^^^^^^^^^^^
-
-Sometimes a request should fail, for instance if an author with id 1 is requested but does not exist. In that case use an appropriate `HTTP error code <https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error>`_ to signal the client that an error occurred.
-
-Each response subclass has access to the **setStatus** method which lets you set an HTTP status code. To return a JSONResponse signaling that the author with id 1 has not been found, use the following code:
-
-.. code-block:: php
 
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http;
-    use OCP\AppFramework\Http\JSONResponse;
-
-    class AuthorController extends Controller {
-
-        public function show($id) {
-            try {
-                // try to get author with $id
-
-            } catch (NotFoundException $ex) {
-                return new JSONResponse(array(), Http::STATUS_NOT_FOUND);
-            }
-        }
-    }
 
 Authentication
 --------------

From 24e4e6b793768c26e151a6d282458b59b2bb3bb5 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 13:38:35 +0100
Subject: [PATCH 08/23] Moving section Authentication

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 100 ++++++++++++------------
 1 file changed, 48 insertions(+), 52 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 022631d5bfb..d1dc2a0ea5d 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -653,12 +653,60 @@ Streamed and lazily rendered responses
 Security considerations
 -----------------------
 
+.. _controller_authentication:
+
 Authentication
 ^^^^^^^^^^^^^^
 
+By default every controller method enforces the maximum security, which is:
+
+* Ensure that the user is admin
+* Ensure that the user is logged in
+* Ensure that the user has passed the two-factor challenge, if applicable
+* Check the CSRF token
+
 Loosening the default restrictions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Most of the time though it makes sense to also allow normal users to access the page and the ``PageController->index()`` method should not check the CSRF token because it has not yet been sent to the client and because of that can't work.
+
+To turn off checks the following *Attributes* can be added before the controller:
+
+* ``#[NoAdminRequired]``: Also users that are not admins can access the page
+* ``#[PublicPage]``: Everyone can access the page without having to log in
+* ``#[NoTwoFactorRequired]``: A user can access the page before the two-factor challenge has been passed (use this wisely and only in two-factor auth apps, e.g. to allow setup during login)
+* ``#[NoCSRFRequired]``: Don't check the CSRF token (use this wisely since you might create a security hole; to understand what it does see `CSRF in the security section <../prologue/security.html#cross-site-request-forgery>`__)
+
+.. note::
+
+    The attributes are only available in Nextcloud 27 or later. In older versions annotations with the same names exist:
+
+    * ``@NoAdminRequired`` instead of ``#[NoAdminRequired]``
+    * ``@PublicPage``` instead of ``#[PublicPage]``
+    * ``@NoTwoFactorRequired``` instead of ``#[NoTwoFactorRequired]``
+    * ``@NoCSRFRequired``` instead of ``#[NoCSRFRequired]``
+
+A controller method that turns off all checks would look like this:
+
+.. code-block:: php
+    :emphasize-lines: 6-7,10-11
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\IRequest;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+    use OCP\AppFramework\Http\Attribute\PublicPage;
+
+    class PageController extends Controller {
+        #[NoCSRFRequired]
+        #[PublicPage]
+        public function freeForAll() {
+
+        }
+    }
+
 Rate limiting
 ^^^^^^^^^^^^^
 
@@ -852,58 +900,6 @@ The following policy for instance allows images, audio and videos from other dom
 
     }
 
-
-
-
-Authentication
---------------
-
-By default every controller method enforces the maximum security, which is:
-
-* Ensure that the user is admin
-* Ensure that the user is logged in
-* Ensure that the user has passed the two-factor challenge, if applicable
-* Check the CSRF token
-
-Most of the time though it makes sense to also allow normal users to access the page and the PageController->index() method should not check the CSRF token because it has not yet been sent to the client and because of that can't work.
-
-To turn off checks the following *Attributes* can be added before the controller:
-
-* ``#[NoAdminRequired]``: Also users that are not admins can access the page
-* ``#[PublicPage]``: Everyone can access the page without having to log in
-* ``#[NoTwoFactorRequired]``: A user can access the page before the two-factor challenge has been passed (use this wisely and only in two-factor auth apps, e.g. to allow setup during login)
-* ``#[NoCSRFRequired]``: Don't check the CSRF token (use this wisely since you might create a security hole; to understand what it does see `CSRF in the security section <../prologue/security.html#cross-site-request-forgery>`__)
-
-.. note::
-
-    The attributes are only available in Nextcloud 27 or later. In older versions annotations with the same names exist:
-
-    * ``@NoAdminRequired`` instead of ``#[NoAdminRequired]``
-    * ``@PublicPage``` instead of ``#[PublicPage]``
-    * ``@NoTwoFactorRequired``` instead of ``#[NoTwoFactorRequired]``
-    * ``@NoCSRFRequired``` instead of ``#[NoCSRFRequired]``
-
-A controller method that turns off all checks would look like this:
-
-.. code-block:: php
-    :emphasize-lines: 6-7,10-11
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\IRequest;
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
-    use OCP\AppFramework\Http\Attribute\PublicPage;
-
-    class PageController extends Controller {
-        #[NoCSRFRequired]
-        #[PublicPage]
-        public function freeForAll() {
-
-        }
-    }
-
 Rate limiting
 -------------
 

From 30c51835df5e8a4d03c88b7c011e6dca87511a3e Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 15:01:55 +0100
Subject: [PATCH 09/23] Move section Content security policy

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 119 ++++++++++++------------
 1 file changed, 58 insertions(+), 61 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index d1dc2a0ea5d..210ef1aa153 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -716,6 +716,64 @@ Brute-force protection
 Modifying the content security policy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`_.
+However if an app relies on third-party media or other features which are forbidden by the current policy the policy can be relaxed.
+
+.. note:: Double check your content and edge cases before you relax the policy! Also read the `documentation provided by MDN <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`_
+
+To relax the policy pass an instance of the ContentSecurityPolicy class to your response. The methods on the class can be chained.
+
+The following methods turn off security features by passing in **true** as the **$isAllowed** parameter
+
+* **allowInlineScript** (bool $isAllowed)
+* **allowInlineStyle** (bool $isAllowed)
+* **allowEvalScript** (bool $isAllowed)
+* **useStrictDynamic** (bool $isAllowed)
+
+  Trust all scripts that are loaded by a trusted script, see 'script-src' and 'strict-dynamic'
+
+* **useStrictDynamicOnScripts** (bool $isAllowed)
+
+  Trust all scripts that are loaded by a trusted script which was loaded using a ``<script>`` tag, see 'script-src-elem' **(enabled by default)**
+
+.. note:: ``useStrictDynamicOnScripts`` is enabled by default to allow module javascript to load its dependencies using ``import`` since Nextcloud 28. You can disable this by passing **false** as the parameter.
+
+The following methods whitelist domains by passing in a domain or \* for any domain:
+
+* **addAllowedScriptDomain** (string $domain)
+* **addAllowedStyleDomain** (string $domain)
+* **addAllowedFontDomain** (string $domain)
+* **addAllowedImageDomain** (string $domain)
+* **addAllowedConnectDomain** (string $domain)
+* **addAllowedMediaDomain** (string $domain)
+* **addAllowedObjectDomain** (string $domain)
+* **addAllowedFrameDomain** (string $domain)
+* **addAllowedChildSrcDomain** (string $domain)
+
+The following policy for instance allows images, audio and videos from other domains:
+
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\TemplateResponse;
+    use OCP\AppFramework\Http\ContentSecurityPolicy;
+
+    class PageController extends Controller {
+
+        public function index() {
+            $response = new TemplateResponse('myapp', 'main');
+            $csp = new ContentSecurityPolicy();
+            $csp->addAllowedImageDomain('*');
+                ->addAllowedMediaDomain('*');
+            $response->setContentSecurityPolicy($csp);
+        }
+
+    }
+
 
 ---
 
@@ -839,67 +897,6 @@ If you want to use a custom, lazily rendered response simply implement the inter
 
 .. note:: Because this code is rendered after several usually built in helpers, you need to take care of errors and proper HTTP caching by yourself.
 
-Modifying the content security policy
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`_.
-However if an app relies on third-party media or other features which are forbidden by the current policy the policy can be relaxed.
-
-.. note:: Double check your content and edge cases before you relax the policy! Also read the `documentation provided by MDN <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`_
-
-To relax the policy pass an instance of the ContentSecurityPolicy class to your response. The methods on the class can be chained.
-
-The following methods turn off security features by passing in **true** as the **$isAllowed** parameter
-
-* **allowInlineScript** (bool $isAllowed)
-* **allowInlineStyle** (bool $isAllowed)
-* **allowEvalScript** (bool $isAllowed)
-* **useStrictDynamic** (bool $isAllowed)
-
-  Trust all scripts that are loaded by a trusted script, see 'script-src' and 'strict-dynamic'
-
-* **useStrictDynamicOnScripts** (bool $isAllowed)
-
-  Trust all scripts that are loaded by a trusted script which was loaded using a ``<script>`` tag, see 'script-src-elem' **(enabled by default)**
-
-.. note:: ``useStrictDynamicOnScripts`` is enabled by default to allow module javascript to load its dependencies using ``import`` since Nextcloud 28. You can disable this by passing **false** as the parameter.
-
-The following methods whitelist domains by passing in a domain or \* for any domain:
-
-* **addAllowedScriptDomain** (string $domain)
-* **addAllowedStyleDomain** (string $domain)
-* **addAllowedFontDomain** (string $domain)
-* **addAllowedImageDomain** (string $domain)
-* **addAllowedConnectDomain** (string $domain)
-* **addAllowedMediaDomain** (string $domain)
-* **addAllowedObjectDomain** (string $domain)
-* **addAllowedFrameDomain** (string $domain)
-* **addAllowedChildSrcDomain** (string $domain)
-
-The following policy for instance allows images, audio and videos from other domains:
-
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\TemplateResponse;
-    use OCP\AppFramework\Http\ContentSecurityPolicy;
-
-    class PageController extends Controller {
-
-        public function index() {
-            $response = new TemplateResponse('myapp', 'main');
-            $csp = new ContentSecurityPolicy();
-            $csp->addAllowedImageDomain('*');
-                ->addAllowedMediaDomain('*');
-            $response->setContentSecurityPolicy($csp);
-        }
-
-    }
-
 Rate limiting
 -------------
 

From c2040e8c5c6e59fca6057b32054fe17d55b67a0a Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 13:38:35 +0100
Subject: [PATCH 10/23] Moving section Redirects

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 39 ++++++++++++-------------
 1 file changed, 18 insertions(+), 21 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 210ef1aa153..540d6711992 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -641,6 +641,24 @@ Miscellaneous responses
 Redirects
 ^^^^^^^^^
 
+A redirect can be achieved by returning a RedirectResponse:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\RedirectResponse;
+
+    class PageController extends Controller {
+
+        public function toGoogle(): RedirectResponse {
+            return new RedirectResponse('https://google.com');
+        }
+
+    }
+
 Downloads
 ^^^^^^^^^
 
@@ -777,27 +795,6 @@ The following policy for instance allows images, audio and videos from other dom
 
 ---
 
-Redirects
-^^^^^^^^^
-
-A redirect can be achieved by returning a RedirectResponse:
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\RedirectResponse;
-
-    class PageController extends Controller {
-
-        public function toGoogle(): RedirectResponse {
-            return new RedirectResponse('https://google.com');
-        }
-
-    }
-
 Downloads
 ^^^^^^^^^
 

From 0ac03ca9000998998a280596dfa51290db198393 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 16:00:52 +0100
Subject: [PATCH 11/23] Move section Downloads

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 45 ++++++++++++-------------
 1 file changed, 21 insertions(+), 24 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 540d6711992..9ae99dc5226 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -662,6 +662,27 @@ A redirect can be achieved by returning a RedirectResponse:
 Downloads
 ^^^^^^^^^
 
+A file download can be triggered by returning a DownloadResponse:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\DownloadResponse;
+
+    class PageController extends Controller {
+
+        public function downloadXMLFile(): DownloadResponse {
+            $path = '/some/path/to/file.xml';
+            $contentType = 'application/xml';
+
+            return new DownloadResponse($path, $contentType);
+        }
+
+    }
+
 Creating custom responses
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -795,30 +816,6 @@ The following policy for instance allows images, audio and videos from other dom
 
 ---
 
-Downloads
-^^^^^^^^^
-
-A file download can be triggered by returning a DownloadResponse:
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\DownloadResponse;
-
-    class PageController extends Controller {
-
-        public function downloadXMLFile(): DownloadResponse {
-            $path = '/some/path/to/file.xml';
-            $contentType = 'application/xml';
-
-            return new DownloadResponse($path, $contentType);
-        }
-
-    }
-
 Creating custom responses
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 

From ef9fb32bbaa5384ca16f003d5cf21a46f55d8a1a Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 16:01:27 +0100
Subject: [PATCH 12/23] Move section custom responses

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 59 ++++++++++++-------------
 1 file changed, 28 insertions(+), 31 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 9ae99dc5226..77c89233ba8 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -686,6 +686,34 @@ A file download can be triggered by returning a DownloadResponse:
 Creating custom responses
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
+If no premade Response fits the needed use case, it is possible to extend the Response base class and custom Response. The only thing that needs to be implemented is the **render** method which returns the result as string.
+
+Creating a custom XMLResponse class could look like this:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Http;
+
+    use OCP\AppFramework\Http\Response;
+
+    class XMLResponse extends Response {
+
+        private array $xml;
+
+        public function __construct(array $xml) {
+            $this->addHeader('Content-Type', 'application/xml');
+            $this->xml = $xml;
+        }
+
+        public function render(): string {
+            $root = new SimpleXMLElement('<root/>');
+            array_walk_recursive($this->xml, array ($root, 'addChild'));
+            return $xml->asXML();
+        }
+
+    }
+
 Streamed and lazily rendered responses
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -816,37 +844,6 @@ The following policy for instance allows images, audio and videos from other dom
 
 ---
 
-Creating custom responses
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If no premade Response fits the needed use case, it is possible to extend the Response base class and custom Response. The only thing that needs to be implemented is the **render** method which returns the result as string.
-
-Creating a custom XMLResponse class could look like this:
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Http;
-
-    use OCP\AppFramework\Http\Response;
-
-    class XMLResponse extends Response {
-
-        private array $xml;
-
-        public function __construct(array $xml) {
-            $this->addHeader('Content-Type', 'application/xml');
-            $this->xml = $xml;
-        }
-
-        public function render(): string {
-            $root = new SimpleXMLElement('<root/>');
-            array_walk_recursive($this->xml, array ($root, 'addChild'));
-            return $xml->asXML();
-        }
-
-    }
-
 Streamed and lazily rendered responses
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

From ef54c9ef4c8c44b80c583251b5b1681c86c0c1f7 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 16:02:35 +0100
Subject: [PATCH 13/23] Move section Streamed/lazily rendered Content

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 81 ++++++++++++-------------
 1 file changed, 38 insertions(+), 43 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 77c89233ba8..d93075221a0 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -717,6 +717,44 @@ Creating a custom XMLResponse class could look like this:
 Streamed and lazily rendered responses
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+By default all responses are rendered at once and sent as a string through middleware. In certain cases this is not a desirable behavior, for instance if you want to stream a file in order to save memory. To do that use the now available **OCP\\AppFramework\\Http\\StreamResponse** class:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\StreamResponse;
+
+    class PageController extends Controller {
+
+        public function downloadXMLFile() {
+            return new StreamResponse('/some/path/to/file.xml');
+        }
+
+    }
+
+If you want to use a custom, lazily rendered response simply implement the interface **OCP\\AppFramework\\Http\\ICallbackResponse** for your response:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Http;
+
+    use OCP\AppFramework\Http\Response;
+    use OCP\AppFramework\Http\ICallbackResponse;
+
+    class LazyResponse extends Response implements ICallbackResponse {
+
+        public function callback(IOutput $output) {
+            // custom code in here
+        }
+
+    }
+
+.. note:: Because this code is rendered after several usually built in helpers, you need to take care of errors and proper HTTP caching by yourself.
+
 Security considerations
 -----------------------
 
@@ -844,49 +882,6 @@ The following policy for instance allows images, audio and videos from other dom
 
 ---
 
-Streamed and lazily rendered responses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default all responses are rendered at once and sent as a string through middleware. In certain cases this is not a desirable behavior, for instance if you want to stream a file in order to save memory. To do that use the now available **OCP\\AppFramework\\Http\\StreamResponse** class:
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\StreamResponse;
-
-    class PageController extends Controller {
-
-        public function downloadXMLFile() {
-            return new StreamResponse('/some/path/to/file.xml');
-        }
-
-    }
-
-
-
-
-If you want to use a custom, lazily rendered response simply implement the interface **OCP\\AppFramework\\Http\\ICallbackResponse** for your response:
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Http;
-
-    use OCP\AppFramework\Http\Response;
-    use OCP\AppFramework\Http\ICallbackResponse;
-
-    class LazyResponse extends Response implements ICallbackResponse {
-
-        public function callback(IOutput $output) {
-            // custom code in here
-        }
-
-    }
-
-.. note:: Because this code is rendered after several usually built in helpers, you need to take care of errors and proper HTTP caching by yourself.
 
 Rate limiting
 -------------

From 7d411004a4f917665ae4727210610949402f602c Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 16:05:12 +0100
Subject: [PATCH 14/23] Move section Rate Limiting

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 78 ++++++++++++-------------
 1 file changed, 38 insertions(+), 40 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index d93075221a0..3c1e7eab66f 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -815,6 +815,44 @@ A controller method that turns off all checks would look like this:
 Rate limiting
 ^^^^^^^^^^^^^
 
+Nextcloud supports rate limiting on a controller method basis and in a :ref:`programmatic way<programmatic-rate-limiting>`. By default controller methods are not rate limited. Rate limiting should be used on expensive or security sensitive functions (e.g. password resets) to increase the overall security of your application.
+
+The native rate limiting will return a 429 status code to clients when the limit is reached and a default Nextcloud error page. When implementing rate limiting in your application, you should thus consider handling error situations where a 429 is returned by Nextcloud.
+
+To enable rate limiting the following *Attributes* can be added to the controller:
+
+* ``#[UserRateLimit(limit: int, period: int)]``: The rate limiting that is applied to logged-in users. If not specified Nextcloud will fallback to ``AnonRateLimit`` if available.
+* ``#[AnonRateLimit(limit: int, period: int)]``: The rate limiting that is applied to guests.
+
+.. note::
+
+    The attributes are only available in Nextcloud 27 or later. In older versions the ``@UserRateThrottle(limit=int, period=int)`` and ``@AnonRateThrottle(limit=int, period=int)`` annotation can be used. If both are present, the attribute will be considered first.
+
+A controller method that would allow five requests for logged-in users and one request for anonymous users within the last 100 seconds would look as following:
+
+.. code-block:: php
+    :emphasize-lines: 14-15
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\IRequest;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\Attribute\AnonRateLimit;
+    use OCP\AppFramework\Http\Attribute\UserRateLimit;
+
+    class PageController extends Controller {
+
+        /**
+         * @PublicPage
+         */
+        #[UserRateLimit(limit: 5, period: 100)]
+        #[AnonRateLimit(limit: 1, period: 100)]
+        public function rateLimitedForAll() {
+
+        }
+    }
+
 Brute-force protection
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -883,46 +921,6 @@ The following policy for instance allows images, audio and videos from other dom
 ---
 
 
-Rate limiting
--------------
-
-Nextcloud supports rate limiting on a controller method basis and in a :ref:`programmatic way<programmatic-rate-limiting>`. By default controller methods are not rate limited. Rate limiting should be used on expensive or security sensitive functions (e.g. password resets) to increase the overall security of your application.
-
-The native rate limiting will return a 429 status code to clients when the limit is reached and a default Nextcloud error page. When implementing rate limiting in your application, you should thus consider handling error situations where a 429 is returned by Nextcloud.
-
-To enable rate limiting the following *Attributes* can be added to the controller:
-
-* ``#[UserRateLimit(limit: int, period: int)]``: The rate limiting that is applied to logged-in users. If not specified Nextcloud will fallback to ``AnonRateLimit`` if available.
-* ``#[AnonRateLimit(limit: int, period: int)]``: The rate limiting that is applied to guests.
-
-.. note::
-
-    The attributes are only available in Nextcloud 27 or later. In older versions the ``@UserRateThrottle(limit=int, period=int)`` and ``@AnonRateThrottle(limit=int, period=int)`` annotation can be used. If both are present, the attribute will be considered first.
-
-A controller method that would allow five requests for logged-in users and one request for anonymous users within the last 100 seconds would look as following:
-
-.. code-block:: php
-    :emphasize-lines: 14-15
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\IRequest;
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\Attribute\AnonRateLimit;
-    use OCP\AppFramework\Http\Attribute\UserRateLimit;
-
-    class PageController extends Controller {
-
-        /**
-         * @PublicPage
-         */
-        #[UserRateLimit(limit: 5, period: 100)]
-        #[AnonRateLimit(limit: 1, period: 100)]
-        public function rateLimitedForAll() {
-
-        }
-    }
 
 Brute-force protection
 ----------------------

From 27c0ce5720decd5fd01db32b4baeca5554d0645e Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 16:06:42 +0100
Subject: [PATCH 15/23] Move section brute-force protection

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 134 ++++++++++++------------
 1 file changed, 65 insertions(+), 69 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 3c1e7eab66f..9994a92018d 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -856,75 +856,6 @@ A controller method that would allow five requests for logged-in users and one r
 Brute-force protection
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Modifying the content security policy
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`_.
-However if an app relies on third-party media or other features which are forbidden by the current policy the policy can be relaxed.
-
-.. note:: Double check your content and edge cases before you relax the policy! Also read the `documentation provided by MDN <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`_
-
-To relax the policy pass an instance of the ContentSecurityPolicy class to your response. The methods on the class can be chained.
-
-The following methods turn off security features by passing in **true** as the **$isAllowed** parameter
-
-* **allowInlineScript** (bool $isAllowed)
-* **allowInlineStyle** (bool $isAllowed)
-* **allowEvalScript** (bool $isAllowed)
-* **useStrictDynamic** (bool $isAllowed)
-
-  Trust all scripts that are loaded by a trusted script, see 'script-src' and 'strict-dynamic'
-
-* **useStrictDynamicOnScripts** (bool $isAllowed)
-
-  Trust all scripts that are loaded by a trusted script which was loaded using a ``<script>`` tag, see 'script-src-elem' **(enabled by default)**
-
-.. note:: ``useStrictDynamicOnScripts`` is enabled by default to allow module javascript to load its dependencies using ``import`` since Nextcloud 28. You can disable this by passing **false** as the parameter.
-
-The following methods whitelist domains by passing in a domain or \* for any domain:
-
-* **addAllowedScriptDomain** (string $domain)
-* **addAllowedStyleDomain** (string $domain)
-* **addAllowedFontDomain** (string $domain)
-* **addAllowedImageDomain** (string $domain)
-* **addAllowedConnectDomain** (string $domain)
-* **addAllowedMediaDomain** (string $domain)
-* **addAllowedObjectDomain** (string $domain)
-* **addAllowedFrameDomain** (string $domain)
-* **addAllowedChildSrcDomain** (string $domain)
-
-The following policy for instance allows images, audio and videos from other domains:
-
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\Controller;
-
-    use OCP\AppFramework\Controller;
-    use OCP\AppFramework\Http\TemplateResponse;
-    use OCP\AppFramework\Http\ContentSecurityPolicy;
-
-    class PageController extends Controller {
-
-        public function index() {
-            $response = new TemplateResponse('myapp', 'main');
-            $csp = new ContentSecurityPolicy();
-            $csp->addAllowedImageDomain('*');
-                ->addAllowedMediaDomain('*');
-            $response->setContentSecurityPolicy($csp);
-        }
-
-    }
-
-
----
-
-
-
-Brute-force protection
-----------------------
-
 Nextcloud supports brute-force protection on an action basis. By default controller methods are not protected. Brute-force protection should be used on security sensitive functions (e.g. login attempts) to increase the overall security of your application.
 
 The native brute-force protection will slow down requests if too many violations have been found. This slow down will be applied to all requests against a brute-force protected controller with the same action from the affected IP.
@@ -996,3 +927,68 @@ A controller can also have multiple factors to brute force against. In this case
             return $templateResponse;
         }
     }
+
+Modifying the content security policy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`_.
+However if an app relies on third-party media or other features which are forbidden by the current policy the policy can be relaxed.
+
+.. note:: Double check your content and edge cases before you relax the policy! Also read the `documentation provided by MDN <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`_
+
+To relax the policy pass an instance of the ContentSecurityPolicy class to your response. The methods on the class can be chained.
+
+The following methods turn off security features by passing in **true** as the **$isAllowed** parameter
+
+* **allowInlineScript** (bool $isAllowed)
+* **allowInlineStyle** (bool $isAllowed)
+* **allowEvalScript** (bool $isAllowed)
+* **useStrictDynamic** (bool $isAllowed)
+
+  Trust all scripts that are loaded by a trusted script, see 'script-src' and 'strict-dynamic'
+
+* **useStrictDynamicOnScripts** (bool $isAllowed)
+
+  Trust all scripts that are loaded by a trusted script which was loaded using a ``<script>`` tag, see 'script-src-elem' **(enabled by default)**
+
+.. note:: ``useStrictDynamicOnScripts`` is enabled by default to allow module javascript to load its dependencies using ``import`` since Nextcloud 28. You can disable this by passing **false** as the parameter.
+
+The following methods whitelist domains by passing in a domain or \* for any domain:
+
+* **addAllowedScriptDomain** (string $domain)
+* **addAllowedStyleDomain** (string $domain)
+* **addAllowedFontDomain** (string $domain)
+* **addAllowedImageDomain** (string $domain)
+* **addAllowedConnectDomain** (string $domain)
+* **addAllowedMediaDomain** (string $domain)
+* **addAllowedObjectDomain** (string $domain)
+* **addAllowedFrameDomain** (string $domain)
+* **addAllowedChildSrcDomain** (string $domain)
+
+The following policy for instance allows images, audio and videos from other domains:
+
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\TemplateResponse;
+    use OCP\AppFramework\Http\ContentSecurityPolicy;
+
+    class PageController extends Controller {
+
+        public function index() {
+            $response = new TemplateResponse('myapp', 'main');
+            $csp = new ContentSecurityPolicy();
+            $csp->addAllowedImageDomain('*');
+                ->addAllowedMediaDomain('*');
+            $response->setContentSecurityPolicy($csp);
+        }
+
+    }
+
+
+---
+

From 0935fa8ff5764acc025f4b83d01b5259e4adfe0e Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 13:52:05 +0100
Subject: [PATCH 16/23] Adding some introductions to new chapter structure

Introduction to responders

Introduction HTML responses

Introduction to data responses

Introduction special reponders

Introduction security considerations

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 9994a92018d..e2a0d839dfd 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -342,11 +342,21 @@ Responses
 Similar to how every controller receives a request object, every controller method has to return a Response.
 This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder.
 
+There are different kinds of responses available, like HTML-based responses, data responses, or other.
+The app decides of which kind the response is, by returning an appropriate ``Response`` object in the corresponding controller method.
+The following sections give an overview over the various kinds and how to implement them.
+
 .. _controller_html_responses:
 
 HTML-based Responses
 --------------------
 
+HTML pages are typically served using template responses.
+This is typically used as a starting point to load the website.
+This code linked by the template is by default encapsulated by the server to provide some common styling (e.g. the header row).
+The code then uses JavaScript to load further components (see :ref:`Frontend building in Vue<ApplicationJs>`) and the actual data.
+This section only focuses on the actual HTML content, not the data to fill into the dynamic pages.
+
 .. _controller_template:
 
 Templates
@@ -428,6 +438,12 @@ class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interf
 Data-based responses
 --------------------
 
+In contrast to the HTML template responses, the data responses return some user-data in packed form.
+There are different encodings thinkable like JSON, XML, or other formats.
+The main point is that the data is requested by the browser using JavaScript on behalf of the shown website.
+The user only indirectly requested the data by user interaction with the frontend.
+
+
 .. _ocscontroller:
 
 OCS
@@ -638,6 +654,9 @@ Because returning values works fine in case of a success but not in case of fail
 Miscellaneous responses
 -----------------------
 
+Some special responses are available as well.
+These are discussed here.
+
 Redirects
 ^^^^^^^^^
 
@@ -758,6 +777,9 @@ If you want to use a custom, lazily rendered response simply implement the inter
 Security considerations
 -----------------------
 
+Depending on your use-case, you can tighten or loosen the security measurements installed by default on the routes.
+This section gives you a quick overview over the options.
+
 .. _controller_authentication:
 
 Authentication

From bc321ab0d1221fb9732545efa45481a83575d98a Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 13:54:27 +0100
Subject: [PATCH 17/23] Update some texts to reflect current situation better

Update OCS migration text

Fix OCS routes entry

Responders on OCS

APIRoute on 29

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index e2a0d839dfd..83f0a8e5de1 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -452,8 +452,8 @@ OCS
 .. note::
     This is purely for compatibility reasons. If you are planning to offer an external API, go for a :ref:`REST APIs <rest-apis>` instead.
 
-In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added.
-To migrate your API you can use the **OCP\\AppFramework\\OCSController** base class and return your data in the form of a DataResponse in the following way:
+In order to simplify exchange of data between the Nextcloud backend and any client (be it the web frontend or whatever else), the OCS API has been introduced.
+To use OCS in your API you can use the **OCP\\AppFramework\\OCSController** base class and return your data in the form of a **DataResponse** in the following way:
 
 .. code-block:: php
 
@@ -475,9 +475,14 @@ To migrate your API you can use the **OCP\\AppFramework\\OCSController** base cl
 
     }
 
-The format parameter works out of the box, no intervention is required.
+For ``OCSController`` classes and their methods, :ref:`responders <controller-responders>` can be registered as with any other ``Controller`` method.
+The ``OCSController`` class have however automatically two responders pre-installed:
+Both JSON (``application/json``) and XML (``text/xml``) are generated on-the-fly depending on the request by the browser/user.
+To select the output format, the ``?format=`` query parameter or the ``Accept`` header of the request work out of the box, no intervention is required.
+It is advised to prefer the header generally, as this is the more programmatic way.
 
-In order to make routing work for OCS routes you need to add a separate ‘ocs’ entry to the routing table of your app. Inside these are normal routes.
+In order to make routing work for OCS routes you need to add :ref:`a separate 'ocs' entry<routes_ocs>` to the routing table in ``appinfo/routes.php`` of your app.
+Inside these, there are the same information as there are for normal routes.
 
 .. code-block:: php
 
@@ -495,6 +500,10 @@ In order to make routing work for OCS routes you need to add a separate ‘ocs
 
 Now your method will be reachable via ``<server>/ocs/v2.php/apps/<APPNAME>/api/v1/shares``
 
+.. versionadded:: 29
+    You can use the attribute ``ApiRoute`` as described in :doc:`Routing <routing>` instead of the entry in ``appinfo/routes.php`` as an alternative.
+
+
 JSON
 ^^^^
 

From 9388034295ce7042958e27b595bd339692bcdbc6 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 14:00:32 +0100
Subject: [PATCH 18/23] Make CSRF check clearer

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 83f0a8e5de1..5b34aa585b7 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -799,7 +799,10 @@ By default every controller method enforces the maximum security, which is:
 * Ensure that the user is admin
 * Ensure that the user is logged in
 * Ensure that the user has passed the two-factor challenge, if applicable
-* Check the CSRF token
+* Ensure the request is no CSRF attack, that is at least one of the following:
+
+  - Ensure the CSRF token is present and valid
+  - Ensure the ``OCS-APIRequest`` header is present and set to ``true`` [1]_
 
 Loosening the default restrictions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1023,3 +1026,5 @@ The following policy for instance allows images, audio and videos from other dom
 
 ---
 
+.. [1] Even though the header name ``OCS-APIRequest`` hints purely at OCS controllers, with NC 30 classic controller methods respect this header as well.
+       Until NC 30, classical controller methods did not respect the header.

From d3348cd2b742919da5fff8a450550fa5c8619818 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 14:02:24 +0100
Subject: [PATCH 19/23] Add more examples in the Authentication section

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 71 +++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 5b34aa585b7..9f1ea73d44a 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -825,6 +825,77 @@ To turn off checks the following *Attributes* can be added before the controller
     * ``@NoTwoFactorRequired``` instead of ``#[NoTwoFactorRequired]``
     * ``@NoCSRFRequired``` instead of ``#[NoCSRFRequired]``
 
+In the following some examples of configurations are given.
+
+Showing an HTML page by the user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A typical app needs an ``index.html`` page to show all content within.
+This page should be visible by all users in the instance.
+Therefore, you need to loosen the restriction from admins only (``#[NoAdminRequired]``).
+Additionally, as the user might not have a CSRF checker cookie set yet, the CSRF checks should be disabled (which is fine as this is a template response).
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\TemplateResponse;
+    use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+    use OCP\AppFramework\Http\Attribute\PublicPage;
+
+    class PageController extends Controller {
+
+        #[NoCSRFRequired]
+        #[NoAdminRequired]
+        public function index(): TemplateResponse {
+            return new TemplateResponse($this->appName, 'main');
+        }
+
+    }
+
+If the page should only be visible to the admin, you can keep the restrictive default by omitting the attribute ``#[NoAdminRequired]``.
+
+Getting data from the backend using AJAX requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Data for the frontend needs to be made available from the backend.
+Here, OCS is the suggested way to go.
+Here is the example from :ref:`OCS controllers <ocscontroller>`:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Http\DataResponse;
+    use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+    use OCP\AppFramework\OCSController;
+
+    class ShareController extends OCSController {
+
+        #[NoAdminRequired]
+        public function getShares(): DataResponse {
+            return new DataResponse([
+                // Your data here
+            ]);
+        }
+
+    }
+
+The ``#[NoAdminRequired]`` is needed here as normal users should be able to access the data in fact.
+It can be left out in case only the admin user should be able to access the data.
+The CSRF check is still active.
+Thus, the client must obey the corresponding requirements.
+
+Completely disabled authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+    This is a security issue if the side-effects are not carefully considered.
+    You should only use this for public pages that anyone is allowed to access.
+
 A controller method that turns off all checks would look like this:
 
 .. code-block:: php

From e2b250433852e3b8a1b496600a252a4d22fc2df3 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 14:03:02 +0100
Subject: [PATCH 20/23] Fix some minor punctuation

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 9f1ea73d44a..a9360197d0c 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -335,7 +335,6 @@ Cookies can be set or modified directly on the response class:
         }
    }
 
-
 Responses
 ---------
 
@@ -1094,8 +1093,5 @@ The following policy for instance allows images, audio and videos from other dom
 
     }
 
-
----
-
 .. [1] Even though the header name ``OCS-APIRequest`` hints purely at OCS controllers, with NC 30 classic controller methods respect this header as well.
        Until NC 30, classical controller methods did not respect the header.

From 17043e2dd434cd1bd17a8afb5f33ac3600869d59 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 14:03:55 +0100
Subject: [PATCH 21/23] Update routing file

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/routing.rst | 47 ++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/developer_manual/basics/routing.rst b/developer_manual/basics/routing.rst
index 174f6544f03..acb478d4e7a 100644
--- a/developer_manual/basics/routing.rst
+++ b/developer_manual/basics/routing.rst
@@ -17,16 +17,14 @@ Routes map a URL and a method to a controller method. Routes are defined inside
 
 .. versionadded:: 29
 
-You can also use attributes on the Controller method to define routes.
-They support all the same parameters (except for ``name`` which is not needed).
-``FrontpageRoute`` has to be used for routes that were in the ``routes`` section and ``ApiRoute`` has to be used for routes that were in the ``ocs`` section.
+    You can also use attributes on the Controller method to define routes.
+    They support all the same parameters (except for ``name`` which is not needed).
+    ``FrontpageRoute`` has to be used for routes that were in the ``routes`` section and ``ApiRoute`` has to be used for routes that were in the ``ocs`` section.
 
 .. code-block:: php
 
     #[FrontpageRoute(verb: 'GET', url: '/')]
 
-    #[ApiRoute(verb: 'GET', url: '/')]
-
 The route array contains the following parts:
 
 * **url**: The URL that is matched after */index.php/apps/myapp*
@@ -36,6 +34,45 @@ The route array contains the following parts:
 * **postfix** (Optional): lets you define a route id postfix. Since each route name will be transformed to a route id (**page#method** -> **myapp.page.method**) and the route id can only exist once you can use the postfix option to alter the route id creation by adding a string to the route id, e.g., **'name' => 'page#method', 'postfix' => 'test'** will yield the route id **myapp.page.methodtest**. This makes it possible to add more than one route/URL for a controller method
 * **defaults** (Optional): If this setting is given, a default value will be assumed for each URL parameter which is not present. The default values are passed in as a key => value pair array
 
+.. _routes_ocs:
+
+OCS routes
+----------
+
+Registering of OCS routes requires to use a :ref:`corresponding controller<ocscontroller>`.
+Additionally, the route must be configured to be an OCS route in the router.
+To do so, you use the ``ocs`` key in the ``routes.php`` file instead of the key ``routes``.
+The rest of the structure is the same.
+
+You can of course combine non-OCS with OCS routes.
+
+.. code-block:: php
+
+    <?php
+    return [
+        'routes' => [
+            ['name' => 'page#index', 'url' => '/', 'verb' => 'GET'],
+        ],
+        'ocs' => [
+            ['name' => 'api#data', 'url' => '/v1/data', 'verb' => 'GET'],
+        ],
+    ];
+
+The prefix for OCS routes is ``/ocs/v2.php/apps/<APPNAME>/``.
+So, the configured URL for the OCS endpoint in the example would be ``<server>/ocs/v2.php/apps/<APPNAME>/v1/data``.
+
+.. versionadded:: 29
+    Similar to ``FrontpageRoute``, you can use ``ApiRoute`` as attribute to mark a route in the controller directly.
+
+    This is equivalent to the configuration in the ``routes.php`` above.
+
+    .. code-block:: php
+
+        // In class ApiController that is a OCSController
+        #[ApiRoute(verb: 'GET', url: '/v1/data')]
+        function data() { /* ... */ }
+
+
 Extracting values from the URL
 ------------------------------
 

From 5435dcd708fef828b4199cb9d0356401c47a5da5 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 18:05:11 +0100
Subject: [PATCH 22/23] Apply suggestions from code review

Add first batch of changes to be incorporated.

Co-authored-by: Kate <26026535+provokateurin@users.noreply.github.com>
Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 4 ++--
 developer_manual/basics/routing.rst     | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index a9360197d0c..14896c5a453 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -478,7 +478,7 @@ For ``OCSController`` classes and their methods, :ref:`responders <controller-re
 The ``OCSController`` class have however automatically two responders pre-installed:
 Both JSON (``application/json``) and XML (``text/xml``) are generated on-the-fly depending on the request by the browser/user.
 To select the output format, the ``?format=`` query parameter or the ``Accept`` header of the request work out of the box, no intervention is required.
-It is advised to prefer the header generally, as this is the more programmatic way.
+It is advised to prefer the header generally, as this is the more standardized way.
 
 In order to make routing work for OCS routes you need to add :ref:`a separate 'ocs' entry<routes_ocs>` to the routing table in ``appinfo/routes.php`` of your app.
 Inside these, there are the same information as there are for normal routes.
@@ -883,7 +883,7 @@ Here is the example from :ref:`OCS controllers <ocscontroller>`:
 
     }
 
-The ``#[NoAdminRequired]`` is needed here as normal users should be able to access the data in fact.
+The ``#[NoAdminRequired]`` is needed here as normal users should be able to access the data.
 It can be left out in case only the admin user should be able to access the data.
 The CSRF check is still active.
 Thus, the client must obey the corresponding requirements.
diff --git a/developer_manual/basics/routing.rst b/developer_manual/basics/routing.rst
index acb478d4e7a..13f9336457a 100644
--- a/developer_manual/basics/routing.rst
+++ b/developer_manual/basics/routing.rst
@@ -44,7 +44,7 @@ Additionally, the route must be configured to be an OCS route in the router.
 To do so, you use the ``ocs`` key in the ``routes.php`` file instead of the key ``routes``.
 The rest of the structure is the same.
 
-You can of course combine non-OCS with OCS routes.
+You can of course have both index.php and OCS routes.
 
 .. code-block:: php
 

From b8b0411f1c41ba42e947f1d6d4fec6f9abb96186 Mon Sep 17 00:00:00 2001
From: Christian Wolf <github@christianwolf.email>
Date: Fri, 28 Feb 2025 18:23:27 +0100
Subject: [PATCH 23/23] Apply suggestions from code review

Signed-off-by: Christian Wolf <github@christianwolf.email>
---
 developer_manual/basics/controllers.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst
index 14896c5a453..c8de6729c03 100644
--- a/developer_manual/basics/controllers.rst
+++ b/developer_manual/basics/controllers.rst
@@ -480,7 +480,10 @@ Both JSON (``application/json``) and XML (``text/xml``) are generated on-the-fly
 To select the output format, the ``?format=`` query parameter or the ``Accept`` header of the request work out of the box, no intervention is required.
 It is advised to prefer the header generally, as this is the more standardized way.
 
-In order to make routing work for OCS routes you need to add :ref:`a separate 'ocs' entry<routes_ocs>` to the routing table in ``appinfo/routes.php`` of your app.
+To make routing work for OCS, the route must be registered in the core.
+This can be done in two ways:
+You can add an attribute `#[ApiRoute]` to the controller method.
+Alternatively, you can add :ref:`a separate 'ocs' entry<routes_ocs>` to the routing table in ``appinfo/routes.php`` of your app.
 Inside these, there are the same information as there are for normal routes.
 
 .. code-block:: php