[Question] Exception with Custom Attributes

[johannesschobel]

Dear all,

first of all: thanks a lot for this awesome package! I really love it - keep your work up :)

However, I have a question regarding the Exception Handling, specifically how to add custom fields to exceptions. I would like to make the exceptions thrown JsonAPI-valid (JSON API Errors). I have googled a lot on this problem and tracked down a lot of issues on this project site as well. However, I was not able to solve my problem.

First of all, I have adapted the api.php config file, specifically the errorFormat to meet my demands.

Then I have created an ApiBaseException extending the Symfony\Component\HttpKernel\Exception\HttpException as described in the Wiki Pages (Errors and Error Responses)

The constructor for this Exception looks like this:

public function __construct(..., $title = null, $meta = []) {
   parent::__construct(..., ..., ...);
   $this->title = $title;
   $this->meta = $meta;
}

because i would like to add the fields title and meta to my JSON Exception. For example, the result should look like this:

{ "errors" : {
   "message" : "The Element could not be stored to the database!",
   "code" : "INTERNAL CODE",
   "status" : 500,
   "title" : "ELEMENT_SAVE_ERROR",
   "meta" : {
      "more" : "information",
      "further" : "data"
   }
} }

However, if I throw the exception like this throw new ApiBaseException(..., ..., ..., "ELEMENT_SAVE_ERROR", []); within the controller this further information (e.g., title and meta) is not displayed.

It looks to me, that all information (except the default values provided in the original api.php config file) are omitted. How can I add the additional fields to the JSON Response for exceptions?

I would highly appreciate your answer or contributions to solve my problem. Please let me know, if you need any other information.

Kind regards,

Johannes

[tembra]

Hello @johannesschobel

I got what you want. First we need to clarify the JSON API Errors (http://jsonapi.org/format/#errors). The documentation says that "Error objects MUST be returned as an array keyed by errors in the top level of a JSON API document.". Notice that is an ARRAY keyed by errors that needs to be in the top level (root), but the documentation DOES NOT says that needs to be the ONLY ONE in your response.

So your example above is an invalid JSON API Error answer. BTW the two JSON API answers below are valid. Notice that first one doesn't have the jsonapi key and errors is an array with one or more object inside:

{
  "errors" : [
      {
        "status" : 500,
        "code" : "INTERNAL CODE",
        "title" : "ELEMENT_SAVE_ERROR",
        "meta" : {
          "more" : "information",
          "further" : "data"
        }
      }
  ]
}

{
  "jsonapi" : {
    "version": "1.0"
  },
  "errors" : [
      {
        "status" : 500,
        "code" : "INTERNAL CODE",
        "title" : "ELEMENT_SAVE_ERROR",
        "meta" : {
          "more" : "information",
          "further" : "data"
        }
      },
      {
        "status" : 500,
        "code" : "ANOTHER INTERNAL CODE",
        "title" : "ANOTHER_ELEMENT_ERROR",
      }
  ]
}

Notice that the second example includes not only the errors top-level member, but the jsonapi top-level member. Error responses may not contain the top-level data member, but can include all the other top-level members JSON API defines.

More examples can be viewed on http://jsonapi.org/examples/#error-objects
If it was clarified, we can go on.

Like said on Dingo API's documentation (https://github.com/dingo/api/wiki/Errors-And-Error-Responses) "The package automatically catches the thrown exception and will convert it into its JSON representation". This JSON representation is NOT in the JSON API Error format. It is defined in the original api.php config file like you said, and yes, all the other stuff that isn't there will be omitted.

So we need to write our own exception that extends HttpException or implements HttpExceptionInterface like stated on documentation. But we also need a custom exception response, because we need to add our stuff and we can't simply change the errorFormat key on api.php config file because the API doesn't have functions to translate our :stuff to something.

To change the response, we only need to register our new exception like stated on documentation (https://github.com/dingo/api/wiki/Errors-And-Error-Responses#custom-exception-responses) and give the appropriate response on JSON API Error format.

This is the easy way to write your own exception and give a custom response.

The another post you noticed, I did something different. I didn't want to register a custom response, I wanted to use the errorFormat of Dingo API. So I created my own exception that extends HttpException but also implements MessageBagErrors, because I saw that internally Dingo API use the methods implemented on this interface to translate the :errors on errorFormat used on Dingo API's ResourceException.

BTW I also implemented my exception on JSON API Error format like you want to do (except for top-level keys because I use the Dingo API error format). Actually I did a generic trait that I just need to use on my every new ErrorCode class on every new app. This class has constants for error codes and a static property array $titleDetail with title and detail for each constant. BTW code, title and detail from JSON API Error is everything that I did on this trait yet. Maybe when I add all other stuff I can send a pull request to Dingo API and @jasonlewis.

Hope it can helps.

[johannesschobel]

Dear @tembra ,

thanks a lot for your very fast and detailed response regarding my JSON API Error format problem.

In fact, I do know that the JSON API Errors shall allow for multiple error messages. In my case, it would be completely sufficient if one error would be sent (e.g., consider, for example, a ObjectNotFoundException which is thrown inside a controller's method. It may not be possible to continue with the execution of the function, as a crucial object is missing!).

I digged a little bit deeper and thought, that it might be best, if we could edit the protected function prepareReplacements(Exception $exception) method within the Dingo\Api\Exception\Handler class.

This method is responsible for building the replacement-array, which is used to replace the :stuff placeholders within the errorFormat defined in the api.php config file. What do you ( @tembra , @jasonlewis ) think about this idea?

I have created a quick & dirty patch, allowing to dynamically populate the errorFormat. Unfortunately, I will leave for a business trip in 1 day and do not have the time to make a clean pull request for you guys. However, if you think that this might be a good idea, I will try and write a commit in mid July!?

Greetings from Germany,
Johannes

[tembra]

Hello again,

It is good that you solved the problem.

About your idea, actually I already thought in something like this. But I think it's not necessary to rewrite (edit) the prepareReplacements method. I guess that a best implementation could be to add any :stuff on errorFormat, so prepareReplacements method verifies the existence of getStuff method on class (our own exception) and if it finds, makes the replacement. This way we can implement getStuff by ourselves, and doing whatever we want without replace/edit/rewrite any method.

What do you think about this @jasonlewis ?

[johannesschobel]

Hey,

I will try to put a small example together when I am back from my business trip. I managed to make only small changes - maybe you guys can take a look at it and discuss if this would be an acceptable way to handle this problem (IF you think, that this IS in fact a problem ;) )

Cheers,
Johannes

[tembra]

Hello again,

@johannesschobel and @jasonlewis I have worked on these last days on error package that implements JSON API Errors.

You can review it on tembra/jsonapi-errors-php. I think it cover practically all situations and I also provide some help to integrate it with Dingo API.

@jasonlewis If you think this package worth a mention in Dingo API Wiki to help persons like @johannesschobel that want to develop an API with JSON API compliant format, I will be glad to help you to do so.

[johannesschobel]

Hey @tembra
you are a beast - awesome work! I will take a look at it and sure will give feedback!
Cheers to you

[hskrasek]

Nice job @tembra on the detailed comments and work. PR's are always welcome, I do have some ideas on how to improve the exception handling, possibly adding a way to access or overwrite the replacements/generic response methods.

Probably wont be in version 1.0.0 though, but hopefully soon afterward.