Review first draft of client and schema docs

I updated the client and schema docs (under API). This currently describes what we *want to have*, not the current state of things. Before going ahead and implementing this let's review this again.

See all `api-` pages in `docs` (or everyhing under API on https://sonar.dev.arso.xyz/docs).