[GENERAL] Document API responses

[raintonr]

I notice there are various REST requests documented in the readme.md. However, there are no responses described. For completeness the responses to each request on success/failure should be documented.

[sworteu]

It's hard to understand the http evok responses without documentation. it's true.

[wesleydv]

I believe this issue is bigger than just the API responses. Documentation of the API should be way better than what it is now.
All the request, their arguments and their possible responses should be documented, preferably in a structured way.

A possible way of doing this would be using the OpenAPI Specification, maybe in combination with a tool like https://editor.swagger.io/
However the OpenAPI Specification does not support RPC.
But just documenting the REST API alone would be a huge step forward.

[tknot]

We have a tentative implementation of JSON schema for the Rest API, which can be used to import into certain API services (we are thinking of using RAML specifically, but it's fully convertible to swagger as well).

We are planning of doing something similar, though it probably won't make it into the next release (due sometime this week) just yet, as there is quite a bit of work involved in implementing it.

[tknot]

The API responses are now documented in the API-DOCS.IO link. It uses similar format as swagger, but it has custom additions to allow us to represent some things that Swagger cannot do (polymorphic arrays in particular, at least without remaking the API to use Swaggers discriminator, see OAI/OpenAPI-Specification#333 in particular)

You can also download the schema from api-docs in OAS (i.e. Swagger) or RAML format.