OK, I know the documentation is not really good there. (remind myself to extend this). I try to explain as much as I can about it.
Note that REST is not CORS. We are comparing in fact 3 different things here:
- REST-based access (without CORS enabled) to get data from the backend to the frontend of the app
- Using OCS to get data from the backend to the frontend or other apps of the user
- Using REST with CORS enabled to get data from the backend to external hosts
Note that if you read carefully, you will find that 1 is considered legacy over 2. This is also true as the NC internal openapi app works better (explanation below) with 2 than with 1.
So far we only exchanged data with the forntend of the NC instance. This has the benefit that the host is the same as the backend which disables some browser-embedded security features (CORS). Once we leave this assumption, new considerations come to play.
If the client is a native app or something in this direction (no Webapp!) 1 and 2 are equal in terms of security but again 2 is in favor of having a cleaner structure.
If the client is a foreign webapp, things gets more complicated. Now, CORS must be enabled, which is true for 3 and 2 (2 makes this by default). So, with 2 you are good to go and done if that works. However, the additional encapsulation is something more or less NC-specific. So, if you want to provide data to third parties in a dedicated format, you will have to fall back to solution 3 (to allow external web applications to access the data).
One point on the preference of 2 over 1:
If you want to allow both the web frontend and external apps to access the endpoints, you have the problem that you want to have one endpoint with CSRF enabled (a cookie set by the server frontend is required for the request to succeed to prevent scripting attacks on the frontend). This is used for the frontend access.
For the external app access (both web and native), the CSRF must be disabled rendering these endpoints more vulnerable by definition. The endpoint can have CORS enabled at no additional cost.
If you used the external endpoint with the web frontend you have multiple issues to address/think of:
- The CSRF check is not active. OK, it will work but this is a small security weakening that might trigger more severe issues.
- The request to a CORS endpoint will invalidate the session. This is a security measurement to enforce transmission of a password/token every time. Your user will get logged of in this case.
With OCS you get everything in one single controller.
I have to admit, this is not by design of the security measures but how these are implemented and what seemed the best solution in average. I do not want to criticize here just state the facts.
Long story short: If you have no special requirements, go with OCS and benefit from the work done for you already.