Docs: Update REST documentation and mkdocs

[vdiezel]

• Target version: main

Summary

PR purely working on the docs.

At my current company we build a custom React frontend for the deck app using the REST API. I've had the docs page open for weeks and I have encountered a number of small issues / missing information in the docs that I retrieved from the code base instead. I compiled a bunch of information and I though it would be a shame if it gets lost.

Further, the docs are not really nice to navigate because all REST endpoints are within a single page without individual entries in the sidebar for the endpoints. So a lot of scrolling or ctrl+f is involved. There are also no permalinks.

So I have made a series of cleanups on the docs without actually changing much of the content. The commit history is pretty clean (reviewing commit-wise makes sense), so it should be easy to drop certain things you don't like. I tried to minimize "opinionated" changes.

I used the latest version mkdocs. I couldn't find any version hint in the CI/CD, so I assume somebody builds them by hand?

The main changes are:

• mkdocs has moved on. I thought the update was worth it, as it improves e.g. a11y and it was not a lot of changes
  • The pages key was finally removed and replaced with nav
  • stricter validation of heading structure (e.g. every page has to have a level 1 heading). The fix for the heading was quite easy, but I had do this in all pages. All other changes I did are concerned with API.md (REST API)
• added permalinks
• Individual endpoints show up in the sidebar by brief description -> easy navigation
• fixed a bunch of typos, markdown formatting errors, wrong/missing HTTP path, parameters, bodies, responses...
• moved certain definitions into the correct spots
• consolidated the structure of every endpoint definition
• reduced the number of "heading noise" (e.g. the different headings for response codes, they create noise and developers who use REST APIs are familiar with HTTP codes anyway, people mostly wanna see what is returned in the happy path)
• consolidated the language a little bit
• added a section on the "x-nc-deck-session" header
• added the missing documentation for three OCS endpoints: overview/upcoming, /search, cards/clone

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Documentation (manuals or wiki) has been updated or is not required

[github-actions]

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.)