Forms: Provide proper REST-API documentation

[stefan-niedermann]

Is your feature request related to a problem? Please describe.
I am interested in writing an Android client for this app. Therefore i need a proper documentation of the REST-API.

Describe the solution you'd like
Perfect would be something like the API documentation for the Deck-app, but plain text would be OK for the start.

Describe alternatives you've considered

• Digging through your code
• Sniffing what the Web UI does

Additional context
I am the maintainer of the Nextcloud Notes and Nextcloud Deck Android clients. My long term goal is to provide free software alternatives to common used proprietary services (Keep, Trello, Doodle, ...)

Related to https://github.com/nextcloud/polls/issues/879 and to https://github.com/nextcloud/forms/issues/274

[jancborchardt]

I am interested in writing an Android client for this app.

🤯 & 🤩 & ♥

@skjnldsv @jotoeri is anyone of you up for documenting that? :)

[skjnldsv]

Would be pretty great yeah!
I have no available time for this unfortunately :/

[Brennakm]

Hi! I am happy to help with REST API documentation. Just let me know. Thanks!

[jancborchardt]

@Brennakm good stuff! :) @skjnldsv @jotoeri any pointers you could give to @Brennakm on how to get started on that?

[jotoeri]

Hm, i dont know much about the REST-spec. But i think the routes and api-controller are the main thing to start. Everything else should be called from there then. FormsService and Db-calls will be used. Maybe first do a request to getForm($id) to get an impression of the Object-Structure (same to getSubmissions($hash)?). You need to be authenticated as the owner of the form for that.
Hope that helps a bit? 🙈
-> For conrete explanations, if a routine is not clear, just ask... 😉 👍

/appinfo/routes.php
/lib/Controller/ApiController.php
/lib/Service/FormsService.php
/lib/Db

[Brennakm]

@stefan-niedermann Hi! Are you saying you would like the Nextcloud Forms REST API documentation to be hosted on Read the Docs like the documentation you linked? If so, I am happy to look into how to do that.

@jotoeri Thank you for the resources! I will look them over tomorrow and let you know if I have any questions.

[stefan-niedermann]

@Brennakm this one solution. Another one was https://docs.nextcloud.com/ (repository) - main issue was to actually have a proper API documentation in the first place, no matter where it is hosted. 🙂

[jancborchardt]

By the way @Brennakm we have a "Forms team" chat room on our Nextcloud Talk instance. I can invite you there with a guest account if you like? :)

[Brennakm]

@jancborchardt Yes, please do add me to the "Forms team" chat room. I know I'll have plenty of questions for the team as I work on documentation :)

[Brennakm]

@stefan-niedermann If it's okay, I'll start by creating a plain text file. Just so you have some documentation. Then later I can always move the content to somewhere else.

[stefan-niedermann]

Sure, i recommend to have a look to the spreed and deck repositories of nextcloud, both contain a simple docs folder with plain text markdown files. Deploying them with a nice stylesheet is an optional step for the future 🙂

[jancborchardt]

@Brennakm sorry for the late reply, had spotty internet. :) Guest accounts need an email address for invitation, which one should I use?

[Brennakm]

@jancborchardt It's okay. My email is [email protected] Thank you!

[skjnldsv]

OCS api is here.
Need someone to create the documentation! :bow:

[loelkes]

The endpoint looks like an OCS API endpoint but the returned data does not correspond to the OCS scheme

/ocs/v2.php/apps/forms/api/v1/forms returns a list of all forms like [{...}, ...]. But with regards to the OCS API specifications I would expect this to be formatted like {ocs: {meta: {...}, data: [{...}, ...]}}

And I can't retrieve any data because I am stuck with {"message":"CSRF check failed"} even though other endpoints work as expected. Did I miss something?

[skjnldsv]

Hum, maybe we need to adapt the Response class used to return data.
Been a while since I dived into this code, do you have some php skills @loelkes ? :)

[loelkes]

Been a while since I dived into this code, do you have some php skills @loelkes ? :)

Yes, but I'm a bit short on time right now and this also implicated changes in the frontend. If I get on it I'll let you know here.