Add Frequent Use-Case Examples for Backend Setups: How to Combine Routing, Controllers & Responses #13834
Description
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:
| Description | Example | Route | Controller | Response | Remarks |
|---|---|---|---|---|---|
| Serve HTML page | Entrypoint for app | FrontendRoute or routes | Controller | TemplateResponse | |
| Serve public HTML page | Public sharing for anonymous access | FrontendRoute or routes | (Auth)PublicShareController | PublicTemplateResponse | |
| Data transmission | Send data between backend and frontend | ApiRoute or ocs | OCSController | DataResponse | opinionated preference |
| File transmission | Send images between backend and frontend | FrontendRoute or routes | Controller | FileResponse or whatever suits best | |
| Data transmission | Send data between backend and frontend | FrontendRoute or routes | Controller | DataResponse or JSONResponse | as a fallback |
| Data sharing | Allow data to be accessed from foreign websites | ApiRoute or ocs | OCSController | DataResponse | Enable CORS (but understand the implications!) |
| File providing | Access files from foreign website | FrontendRoute or routes | ApiController | as needed | Implement security as needed |
(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 🙃