Issues in /api/doc

[relaxnow]

Some issues found after testing the new API docs on /janus/app.php/api/doc/.

• I now have to supply credentials simply to see the API docs? Isn't it possible to export just the API docs (without the sandbox) and run it on GitHub pages or something like that so I don't need a running Janus just to look up an API capability?
• /api/snapshots, what is a snapshot? What does it do?
• Do we really want to expose / encourage use of XML and HTML outputs? Also HTML is given as an option but doesn't seem to work.
• When I switch the body format to JSON I still need to use a form to submit data with the sandbox?
• I'm missing critical explanation (for SAML2 use) that the name of a connection is equal to the entity id
• When posting a new connection I can state an id and revisionNr.
• What is 'state'? What can I fill in there? I'm missing a lot of descriptions.
• How does 'arpAttributes' work? An 'array of arrays'? Same for the other 'array' types. Also note that 'array' does not mean the same thing in other programming languages (or even in JSON) that it does in PHP.
• When I try to create a new connection with a name from the sandbox I get a 500 error.
• What is a 'connectionRevision' in /api/connections/{connectionRevision}?
• What is a 'connection' in /api/connections/{connection}