From adef92fc9611e54cf63cc9d3385ca5ccd35e8690 Mon Sep 17 00:00:00 2001 From: Christian Wolf Date: Wed, 30 Oct 2024 19:34:02 +0100 Subject: [PATCH] Apply suggestions from code review Fix typos and other errors in the code as suggested by review process Co-authored-by: Kate <26026535+provokateurin@users.noreply.github.com> Signed-off-by: Christian Wolf --- developer_manual/basics/controllers.rst | 6 +++--- developer_manual/digging_deeper/rest_apis.rst | 16 ++++++++-------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst index 65bdc782f54..a8c9d14edc2 100644 --- a/developer_manual/basics/controllers.rst +++ b/developer_manual/basics/controllers.rst @@ -765,12 +765,12 @@ To use OCS in your API you can use the **OCP\\AppFramework\\OCSController** base } For ``OCSController`` classes and their methods, :ref:`responders ` can be registered as with any other ``Controller`` method. -The ``OCSController`` class have however automatically two respo nders pre-installed: +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 parameter or the ``Accept`` header of the request work out of the box, no intervention is required. +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 in ``appinf/routes.php`` of your app. +In order to make routing work for OCS routes you need to add a separate 'ocs' entry to the routing table in ``appinfo/routes.php`` of your app. Inside these are normal routes. .. code-block:: php diff --git a/developer_manual/digging_deeper/rest_apis.rst b/developer_manual/digging_deeper/rest_apis.rst index f4ff8697cae..38e785915d6 100644 --- a/developer_manual/digging_deeper/rest_apis.rst +++ b/developer_manual/digging_deeper/rest_apis.rst @@ -94,9 +94,9 @@ The following combinations of attributes might be relevant for various scenarios #. Plain frontend route: ``Controller`` class #. Plain frontend with CRSF checks disabled: ``Controller`` class and ``#[NoCSRFRequired]`` attribute on the method -#. REST route with CORS enabled: ``Controller`` class and ``#[CORS]`` and ``#[NoCSRFRequired]`` attributes on the route -#. OCS-based route: ``OCSController`` class -#. OCS-based route with CORS enabled: ``OCSController`` class and ``#[CORS]`` attribute on the method +#. Plain frontend route with CORS enabled: ``Controller`` class and ``#[CORS]`` and ``#[NoCSRFRequired]`` attributes on the route +#. OCS route: ``OCSController`` class +#. OCS route with CORS enabled: ``OCSController`` class and ``#[CORS]`` attribute on the method .. warning:: Adding the ``#[NoCRSFRequired]`` attribute imposes a security risk. @@ -114,8 +114,8 @@ These ways depend on your API configuration (what you allow) and on which route - *Access from web frontend* means the user is browses the Nextcloud web frontend with a browser. - *Access from an external app* indicates that the user is not using the normal browser (as logged in) but directly navigates a certain URL. This can be in a new browser tab or an external program (like an Android app or simply a curl command line). -- *Access from external website* means that the user browses some third party web site and *magically* data from your app appears. - Technically, the other website would embed/load/use images, JSON data, or other resources from a URL pointing to the Nextcloud server. +- *Access from external website* means that the user browses some third party web site and data from your Nextcloud server appears. + The other website has to embed/load/use images, JSON data, or other resources from a URL pointing to the Nextcloud server, to be able to do this. .. list-table:: Comparison of different API types :header-rows: 1 @@ -170,6 +170,6 @@ The only exception to this is if you want to provide an API for external usage w Here, the encapsulation introduced in OCS and CSRF checks might be in your way. .. [#] Only if you have set ``#[NoCSRFRequired]``. - OCS controllers have other CSRF checks in place that might with CORS without disabling the CSRF checks completely. - Using the ``OCS-APIREQUEST`` header is also a CSRF protection but is compatible with CORS. -.. [#] The OCS controller needs the request header ``OCS-APIREQUEST`` to be set to ``true``. + OCS controllers have other CSRF checks in place that work with CORS without disabling the CSRF checks completely. + Using the ``OCS-APIRequest`` header is a CSRF protection which is compatible with CORS. +.. [#] The OCS controller needs the request header ``OCS-APIRequest`` to be set to ``true``.