There is no tasteful way to provide human readable responses to API requests

[Graham Binns]

At the moment, when we want to send a human-readable response to an API request, we set the content of the HttpResponse, thus:

 >>> return HttpResponse("Couldn't verb the thing", status=httplib.FORBIDDEN)

This isn't particularly tasteful, though. In fact, it's a bit ropey, as Gavin points out in [1]:

> I'm not sure we should do this. The API is for use by other programs.
> One of those programs is the maas CLI. This message is being changed for
> the benefit of the human behind the CLI, but the CLI can also be driven
> by another program, and the API is available to any program.
>
> In this exact case the script can check the return code, where HTTP 200
> OK means all's well. However, this change would set a precedent that I
> don't think we should set: we can't always replace the machine-readable
> output with a human-readable message. Having places where the response
> is for humans and others where it's for machines would give MAAS an even
> more inconsistent API.

Gavin suggests a number of ways to fix this:

1. Do all the translation from machine to human in the CLI.

2. If the human message is short, we could add it as a header to the
   response.

3. Return a multipart response with a machine and human part. This would
   cause a break in compatibility, but it's an easy one to implement at
   least.

After some discussion, we settled on (2), using an X-MAAS-<something> having the least impact; both 1 and 3 are feature-scale work.

 [1] https://code.launchpad.net/~gmb/maas/fix-null-when-releasing-ip-bug-1383668/+merge/239034

[Jason Hobbs (jason-hobbs)]

I have some thoughts on API responses in bug 1353495.

A response could look like:

{
   errors: [{"message": "Frobnication failed.", "code": 42}]
}

With the message for humans and the code for computers. Of course, changing all of our responses to this format would be an API break.

[Andres Rodriguez (andreserl)]

Hi!

We believe this is no longer an issue in the latest MAAS releases. As such, we are marking this bug report as invalid. If you believe this is still an issue, please re-open this bug report.

Thanks