Clarify the description of REST vs OCS in accordance to sugestions discussed #12264

christianlupus · 2024-10-03T18:34:15Z

☑️ Resolves

The statement about OCS to be legacy is removed
A comparison with (plain) REST is made

🖼️ Screenshots

T.B.D.

christianlupus · 2024-10-03T18:41:58Z

@provokateurin I started to rephrase the "do not use OCS" in this PR. Does this sound reasonable or am I going completely the wrong direction? I know I need to eventually write a few more words and I for sure have to check the table entries (and wanted to explain them a bit more).

What do you think, makes this sense? Is this to be discussed with some guys from the core team before merging (as it reverts some basic strategic statement)?

provokateurin

Thanks a lot, this is already super helpful!
The RST syntax for the table really messed with my brain, I need to take a closer look at it in proper table shape.

developer_manual/basics/controllers.rst

developer_manual/conf.py

developer_manual/digging_deeper/rest_apis.rst

christianlupus · 2024-10-07T22:05:41Z

I tried to address the points discussed here. I decided that the CORS should be better put in a separate section as it seems orthogonal to the original question (what should I use Controller or OCSController?).

For simpler reading, I put screenshots of the current state here:

provokateurin

Looks pretty good now!

developer_manual/basics/controllers.rst

developer_manual/digging_deeper/rest_apis.rst

christianlupus · 2024-10-09T22:47:26Z

Updated text:

github-actions · 2024-10-18T02:39:11Z

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)

christianlupus · 2024-10-26T08:15:44Z

@provokateurin are you still looking some things up, is there any action from my side required at the moment, or was there simply no time to review/prepare merging?

provokateurin · 2024-10-27T14:25:28Z

No sorry, I was just busy with other things. I'll take another look in the coming days 👍

provokateurin

Some links to general resources like these would be nice:
https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
https://developer.mozilla.org/en-US/docs/Glossary/CSRF

developer_manual/basics/controllers.rst

developer_manual/digging_deeper/rest_apis.rst

christianlupus · 2025-01-20T16:57:59Z

OK, unfortunately, I had the impression that I needed to restructure the controller chapter. This was a bit back and forth. Many of the changes are just rearrangements. Sorry for the mess. I tried to separate the data from the template requests.

As the changes are lengthy, I would have to copy&paste the complete section here. Thus, instead, I post the built documentation for download: Developer manual.zip

If it helps, I could postpone this PR, rebase the restructuring of thee controller class into a new PR, get that merged, and then come back to this PR here.

provokateurin · 2025-01-27T14:51:34Z

Hm yes this is indeed getting a bit hard to review. A separate PR with only the restructuring would be very appreciated.

christianlupus · 2025-01-29T13:18:58Z

Yeah, I see that. I opened #12549 mostly as a cherry-pick from this to first do the restructuring. Then, this can be worked on easier. Until #12549 is resolved, let's freeze this PR.

provokateurin · 2025-02-28T17:49:17Z

Needs a rebase :)

mejo- · 2025-06-11T06:52:32Z

Just a short note from someone who just started to migrate their app to OCS API with OpenAPI support: getting this PR merged would be a great improvement already. Maybe further improvements can be done in follow-up PRs later on to already profit from the clarifications done so far 😊

Signed-off-by: Christian Wolf <github@christianwolf.email>

Co-authored-by: Kate <26026535+provokateurin@users.noreply.github.com> Signed-off-by: Christian Wolf <github@christianwolf.email>

Signed-off-by: Christian Wolf <github@christianwolf.email>

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 <github@christianwolf.email>

Signed-off-by: Christian Wolf <github@christianwolf.email>

christianlupus · 2025-06-13T17:09:56Z

The main part is in REST vs OCS is this part:

The updated code in the security guidelines:

provokateurin · 2025-06-13T17:44:26Z

I'm a bit busy at the moment, but will give this a proper review in the week after next. I expect that everything will be fine, since we already discussed most changes intensively.

provokateurin

Only found some minor things that need to be changed, otherwise this looks really good!
Feel free to squash everything in the end (or leave it as-is).

developer_manual/digging_deeper/rest_apis.rst

developer_manual/prologue/security.rst

developer_manual/basics/controllers.rst

developer_manual/conf.py

developer_manual/digging_deeper/rest_apis.rst

developer_manual/prologue/security.rst

developer_manual/basics/controllers.rst

Add modifications from reviews Co-authored-by: Joas Schilling <213943+nickvergessen@users.noreply.github.com> Co-authored-by: Kate <26026535+provokateurin@users.noreply.github.com> Signed-off-by: Christian Wolf <github@christianwolf.email>

…est-ocs

Signed-off-by: Christian Wolf <github@christianwolf.email>

Everything was addressed

christianlupus added 2. developing manual: developer labels Oct 3, 2024

provokateurin requested changes Oct 3, 2024

View reviewed changes

christianlupus mentioned this pull request Oct 7, 2024

REST or OCS #12157

Open

provokateurin requested changes Oct 8, 2024

View reviewed changes

developer_manual/basics/controllers.rst Outdated Show resolved Hide resolved

developer_manual/digging_deeper/rest_apis.rst Outdated Show resolved Hide resolved

christianlupus force-pushed the fix/clarification-rest-ocs branch from 08e4aab to ca6794c Compare October 8, 2024 22:33

github-actions bot added the feedback-requested label Oct 18, 2024

provokateurin requested changes Oct 28, 2024

View reviewed changes

christianlupus force-pushed the fix/clarification-rest-ocs branch from adef92f to b7ee67f Compare December 26, 2024 12:34

christianlupus force-pushed the fix/clarification-rest-ocs branch from b7ee67f to 857ad30 Compare January 20, 2025 16:39

christianlupus mentioned this pull request Jan 29, 2025

Restructure significant part of the controller documentation #12549

Merged

christianlupus force-pushed the fix/clarification-rest-ocs branch from 26a5d3f to b0084a7 Compare March 3, 2025 17:16

christianlupus and others added 7 commits June 13, 2025 18:14

Started to fix unclear statements about OCS and REST

1e63339

Signed-off-by: Christian Wolf <github@christianwolf.email>

Fix some sphinx build watrnings

6a9fb9d

Signed-off-by: Christian Wolf <github@christianwolf.email>

Apply suggestions from code review

9b817ad

Co-authored-by: Kate <26026535+provokateurin@users.noreply.github.com> Signed-off-by: Christian Wolf <github@christianwolf.email>

Fix OCS description after some research

5fd856f

Signed-off-by: Christian Wolf <github@christianwolf.email>

Adding CORS back into the mix

64453ed

Signed-off-by: Christian Wolf <github@christianwolf.email>

Apply suggestions from code review

5e0e926

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 <github@christianwolf.email>

Restructure significant part of the controller documentation

2fdeb0b

Signed-off-by: Christian Wolf <github@christianwolf.email>

christianlupus added 6 commits June 13, 2025 18:14

Add basic introduction to CORS in security introduction

86d6bae

Signed-off-by: Christian Wolf <github@christianwolf.email>

Add some paragraph on GET vs other verbs in HTTP

08a8920

Signed-off-by: Christian Wolf <github@christianwolf.email>

Adding some text on historic routing with REST routes

845e062

Signed-off-by: Christian Wolf <github@christianwolf.email>

Add MDN links

146e624

Signed-off-by: Christian Wolf <github@christianwolf.email>

Fix warning in RST code

bda070d

Signed-off-by: Christian Wolf <github@christianwolf.email>

Fix typo

5203eaa

Signed-off-by: Christian Wolf <github@christianwolf.email>

christianlupus force-pushed the fix/clarification-rest-ocs branch from b0084a7 to 5203eaa Compare June 13, 2025 16:16

Reword external app to non-browser

3071dbf

Signed-off-by: Christian Wolf <github@christianwolf.email>

christianlupus marked this pull request as ready for review June 13, 2025 17:04

provokateurin requested changes Jun 20, 2025

View reviewed changes

nickvergessen previously requested changes Jun 20, 2025

View reviewed changes

christianlupus and others added 4 commits July 28, 2025 14:33

Apply suggestions from code review

34756e2

Add modifications from reviews Co-authored-by: Joas Schilling <213943+nickvergessen@users.noreply.github.com> Co-authored-by: Kate <26026535+provokateurin@users.noreply.github.com> Signed-off-by: Christian Wolf <github@christianwolf.email>

Merge remote-tracking branch 'origin/master' into fix/clarification-r…

044c4d7

…est-ocs

Fix issue in config afer merging master

66d1f61

Signed-off-by: Christian Wolf <github@christianwolf.email>

Added content from suggestions

179d774

Signed-off-by: Christian Wolf <github@christianwolf.email>

provokateurin approved these changes Oct 2, 2025

View reviewed changes

provokateurin merged commit c4f7047 into master Oct 2, 2025
13 checks passed

provokateurin deleted the fix/clarification-rest-ocs branch October 2, 2025 09:02

Clarify the description of REST vs OCS in accordance to sugestions discussed #12264

Clarify the description of REST vs OCS in accordance to sugestions discussed #12264

Uh oh!

Conversation

christianlupus commented Oct 3, 2024

☑️ Resolves

🖼️ Screenshots

Uh oh!

christianlupus commented Oct 3, 2024

Uh oh!

provokateurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

christianlupus commented Oct 7, 2024

Uh oh!

provokateurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

christianlupus commented Oct 9, 2024

Uh oh!

github-actions bot commented Oct 18, 2024

Uh oh!

christianlupus commented Oct 26, 2024

Uh oh!

provokateurin commented Oct 27, 2024

Uh oh!

provokateurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

christianlupus commented Jan 20, 2025

Uh oh!

provokateurin commented Jan 27, 2025

Uh oh!

christianlupus commented Jan 29, 2025

Uh oh!

provokateurin commented Feb 28, 2025

Uh oh!

mejo- commented Jun 11, 2025

Uh oh!

christianlupus commented Jun 13, 2025

Uh oh!

provokateurin commented Jun 13, 2025

Uh oh!

provokateurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!