From bc321ab0d1221fb9732545efa45481a83575d98a Mon Sep 17 00:00:00 2001 From: Christian Wolf Date: Fri, 28 Feb 2025 13:54:27 +0100 Subject: [PATCH] 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 --- 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 e2a0d839d..83f0a8e5d 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 ` 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 ` 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` 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 ``/ocs/v2.php/apps//api/v1/shares`` +.. versionadded:: 29 + You can use the attribute ``ApiRoute`` as described in :doc:`Routing ` instead of the entry in ``appinfo/routes.php`` as an alternative. + + JSON ^^^^