Add Frequent Use-Case Examples for Backend Setups: How to Combine Routing, Controllers & Responses

Before You Submit

• I have checked for existing issues and pull requests related to my suggestion.
• I have posted on the Nextcloud Community Help Forum if my suggestion is a troubleshooting scenario or I'm unsure about the solution.

Type of Suggestion

Proposing new documentation content

Relevant Documentation Links

https://docs.nextcloud.com/server/latest/developer_manual/basics/index.html

Summary

Add a table for common combinations of routing, controllers & responses along with their respective effect. Add some additional explanations & references where necessary.

Details

The developer manual already contains the "Basic Concepts" section, where routing, Controllers & Responses are explained. Unfortunately it's somewhat fuzzy how they should be combined for frequent use cases. My take away from a discussion at https://help.nextcloud.com/t/confusion-about-controllers-routes-responses/234873/5 is that the server interface is very flexible and in that flexibility it also allows configurations that are likely not useful for any sensible use case. That flexibility can be confusing for NC-dev newbies like myself, IMO.

I therefore propose to add a new sub-section to the Basics section called "HTTP Endpoints" or similar. This section should contain the existing sections on "Routing" and "Controllers". The content on Responses currently included in the "Controllers" section could be moved to a new standalone "Responses" section. In addition, a new new sub-section on "Combining Routing, Controller & Responses" (or sim) should be added. Core of this section should be a table with frequent use cases:

(based on https://help.nextcloud.com/t/confusion-about-controllers-routes-responses/234873/5)

In addition to this table, the following things surely make sense:

• Some general comments saying that other combinations are perfectly valid if it fits the use case
• a link to https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/rest_apis.html#relation-of-rest-and-ocs

Additional Notes

This issue is a result/spin-off of a discussion with @christianlupus at https://help.nextcloud.com/t/confusion-about-controllers-routes-responses/234873/5. That thread contains some additional points that could be useful documentation improvements, but the one proposed here is IMO the most valuable.

I'm open to draft a proposal for this, but would like to get some approval of the general idea before doing so 🙃

Start with the developer manual Basics page linked in the issue, focusing on the existing Routing, Controllers, and Responses sections. Draft the proposed HTTP Endpoints structure, including a table of frequent routing, controller, and response combinations, general caveats, and the REST/OCS reference link. Done means the new guidance is integrated without losing the existing explanations.