Feature/api user error messages

Background

• With zon APIs, we have a common practice for returning error responses that include a message or messages that are intended to be shown to the user (see DF_REST_Controller and DF_REST_Exception).
• When using a zon endpoint via Laravel-Zon, we need to detect this type of response and ensure it gets through to the front end intact, as it would have if it was a pure Zon API call.

What I did

• Added an exception class for handling cases where an API endpoint wants to respond with an error message or messages that should be shown to the user.
• Updated ZonCaller::doCall to detect and handle cases where the zon-side API endpoint was trying to respond with an error message or messages intended to be show to the end user.

Implications

• This update effectively reproduces the way we handle this need in zon-based systems. We don't necessarily have to do it exactly the same way for Laravel projects, so could consider other alternatives in terms of how we signal these cases to the front end.
• The new ApiUserMessageException class probably needs to go somewhere else, so that pure Laravel endpoints can make use of the same behaviour. Where should we put it?

Setup

None

How to test

• Code review.
• Test with a Laravel-Zon cross platform endpoint, e.g. the Create contract for Shopping Cart or Create purchase from shopping cart calls in Postman. Example Laravel-side endpoint method:

public function createPurchase(Request $request)
{
    try {
        $api = ZonCaller::post('api/v1/loans/create_purchase_from_shopping_cart', \Auth::user(), $request->all());

        $response = $api['body'];

        return $this->respond($response);
    } catch (ApiUserMessageException $exception) {
        throw $exception;
    } catch (\Exception $exception) {
        throw new ApiUserMessageException('Sorry, an unexpected error occurred while setting up the purchase');
    }
}

• In the relevant zon code, try adding calls like the following to test behaviour.

throw new DF_REST_Exception('Sorry dude, that just didn\'t work.');

throw new DF_REST_Exception('I feel like faking a 401 response.', 401);

• Try and break it!
• Consider whether there are better ways to handle this, or variations on it.