centersl/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-03-27 13:38:39 +07:00
Code Issues Packages Projects Releases Wiki Activity

Adding some text on historic routing with REST routes

Browse Source 
Signed-off-by: Christian Wolf <github@christianwolf.email>
This commit is contained in:
Christian Wolf
2025-01-20 17:34:45 +01:00
parent 08a89209e8
commit 845e062cc3
1 changed files with 81 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
developer_manual/digging_deeper/rest_apis.rst
View File

@@ -89,75 +89,76 @@ Relation of REST and OCS
There is a close relationship between REST APIs and :ref:`OCS <ocscontroller>`.
Both provide a way to transmit data between the backend of the app in the Nextcloud server and some frontend.
This is explicitly not about :ref:`HTML template responses <controller_html_responses>`.
State-of-the-Art methods and comparison
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
#. 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.
You should not add this to your controller methods unless you understand the implications and be sure that you absolutely need the attribute.
Typically, you can instead use the ``OCS-APIRequest`` header for data requests, instead.
.. warning::
Adding the attribute ``#[CORS]`` alone is not sufficient to allow access using CORS.
The CSRF checker will typically fail, so enabling CORS enforces you to disable the CSRF checker as well.
Although the disabled CSRF checker in itself is a security issue to consider, adding CORS opens up this even more.
You should make sure, that you understand the implications completely when enabling CORS and do so only when there is a good use case.
Adding the attribute ``#[CORS]`` alone is not sufficient to allow access using CORS with plain frontend routes.
Without further measures, the CSRF checker would fail.
So, enabling CORS for plain controllers is generally and highly discouraged.
You would have to disable the CSRF checker (one more security risk) or use the ``OCP-APIRequest`` header to successfully pass the checker.
The latter requires dedicated JS code on the importing page.
There are different ways a clients might interact with your APIs.
These ways depend on your API configuration (what you allow) and on which route the request is finally made.
- *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 an external app* indicates that the user is not using the normal browser (as logged in) but directly navigates a certain URL directly.
This is typically 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 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.
.. hint::
The discussion here is for data requests only.
If you think of controller :ref:`methods serving (HTML) templates <controller_html_responses>`, disabling CSRF is considered fine.
.. list-table:: Comparison of different API types
:header-rows: 1
:align: center
* - Description
- 1 (plain)
- 2 (w/o CSRF)
- 3 (CORS)
- 4 (OCS)
- 5 (OCS+CORS)
- ``Controller`` class
- ``OCSController`` class
- ``OCSController`` class & ``CORS`` on method
* - URL prefix (relative to server)
- ``/apps/<appid>/``
- ``/apps/<appid>/``
- ``/apps/<appid>/``
- ``/ocs/v2.php/apps/<appid>/``
- ``/ocs/v2.php/apps/<appid>/``
* - Access from web frontend
- yes
- yes (CSRF risk)
- yes (CSRF risk)
- yes
- yes (CSRF risk [#]_)
- yes
* - Access from external app
- ---
- partial [#]_
- yes
- yes
- yes (with header [#]_)
- yes
* - Access from external website
- ---
- ---
- yes
- ---
- yes
* - Encapsulated data
- no
- no
- no
- yes (JSON or XML)
- yes (JSON or XML)
.. [#] The external app has to satisfy the CSRF checks.
That is, you need to have the ``OCS-APIRequest`` HTTP request header set to ``true``.
This is only possible for NC 30 onwards, older versions do not respect the header.
Methods from ``Controller`` classes can return ``DataResponse`` objects similar to ``OCSController`` class methods.
For methods of a ``Controller`` class, the data of this response is sent e.g. as JSON as you provide it.
Basically, the output is very similar to what ``json_encode`` would do.
@@ -169,7 +170,58 @@ As a rule of thumb one can conclude that OCS provides a good way to handle most
The only exception to this is if you want to provide an API for external usage where you have to comply with an externally defined API scheme.
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 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``.
Historical options
~~~~~~~~~~~~~~~~~~
.. deprecated:: 30
The information in this section are mainly for reference purposes. Do not use the approaches in new code.
Before NC server 30 the plain ``Controller`` classes' methods did not respect the ``OCS-APIRequest`` header.
Thus, to provide access to this type of controller methods for external apps, it was necessary to use the ``#[NoCSRFRequired]`` attribute (or the corresponding ``@NoCSRFRequired`` annotation).
The following combinations of attributes were relevant for various scenarios:
#. Plain frontend route: ``Controller`` class
#. Plain frontend with CRSF checks disabled: ``Controller`` class and ``#[NoCSRFRequired]`` 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
.. hint::
The two scenarios involving the ``OCSController`` have not changed and, thus, the state-of-the-art documentation as noted above still holds true.
Thus, these options are not reconsidered here again for simplicity reasons and to get the overall view more crisp.
The warnings about not using ``NoCSRFRequired`` and ``CORS`` as mentioned in the state-of-the-art section holds true here as well.
.. list-table:: Comparison of different API types
:header-rows: 1
:align: center
* - | Description
- | ``Controller`` class
- | ``Controller`` class with
| ``NoCSRFRequired`` on method
- | ``Controller`` class with
| ``NoCSRFRequired`` and ``CORS``
| on method
* - URL prefix (relative to server)
- ``/apps/<appid>/``
- ``/apps/<appid>/``
- ``/apps/<appid>/``
* - Access from web frontend
- yes
- yes (CSRF risk)
- yes (CSRF risk)
* - Access from external app
- ---
- yes
- yes
* - Access from external website
- ---
- ---
- yes
* - Encapsulated data
- no
- no
- no