pmproxy: unify response format

[andreasgerstmayr]

It would be great if the format (structure) of the JSON responses never changes.

For example

• /series/query returns a list of strings on success, and an object in case of failure
• /series/labels?names=hostname returns an object on success, and an empty array if no label values were found

The new PCP Redis datasource is written in Go, i.e. statically typed, and the response will be unmarshalled from JSON into a struct (or list of structs or strings etc.) - therefore it's quite inconvenient if the format of the same API method changes.

I think the LSP spec [1] defines a nice (generic) response format:

interface ResponseMessage extends Message {
	/**
	 * The request id.
	 */
	id: number | string | null;

	/**
	 * The result of a request. This member is REQUIRED on success.
	 * This member MUST NOT exist if there was an error invoking the method.
	 */
	result?: string | number | boolean | object | null;

	/**
	 * The error object in case a request fails.
	 */
	error?: ResponseError;
}

interface ResponseError {
	/**
	 * A number indicating the error type that occurred.
	 */
	code: number;

	/**
	 * A string providing a short description of the error.
	 */
	message: string;

	/**
	 * A primitive or structured value that contains additional
	 * information about the error. Can be omitted.
	 */
	data?: string | number | boolean | array | object | null;
}

We don't need the id, but the rest is great imho - errors also have a code, so the client can react to them (and doesn't need to check for substrings in the error message, which is error prone). The type of result will stay the same for all possible outcomes of a specific API call (in the case of /series/descs, a list of structs (descriptors) for example, and an empty list (or non existent) in the case of an error). Personally this is my favourite of the two examples.

Slack API response is similar [2]:

# on success
{
    "ok": true,
    "stuff": "This is good"
}

# on error
{
    "ok": false,
    "error": "something_bad"
}

# on warning
{
    "ok": true,
    "warning": "something_problematic",
    "stuff": "Your requested information"
}

[1] https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage
[2] https://api.slack.com/web#slack-web-api__evaluating-responses