Add warning section in JSON API spec

1

Hi everyone

I’m kind of resurrecting this thread Multi-status responses (partial success in particular) that is not from me :slight_smile:
but with a different context.

We are following JSON API Standard and one of our API is exposing non mandatory field. One of these fields is for an address. In case an address is filled in, we want to get GPS coordinates through Google MAPS API and store them.
When we are doing our Google MAPS call, multiple scenario can happen:

  1. Everything is fine, we get the coordinates
  2. Google MAPS returns multiple addresses because the provided address is not clear enough
  3. Something bad happened while calling Google MAPS API and we don’t get coordinates.

First case is simple, we save the result and that’s it but the 2 other cases perhaps need user interactions.
We could return an error, saying that we failed to determine the address so something is wrong with it and block the complete resource creation but, address is not a mandatory field and the issue is with some “processing” behind the scene that are not known by our users. In this case, this look weird to us to block the creation because if address wouldn’t have been provided, creation would have been successful.

And at the end, if we are facing issue 2 or 3, we can handle future behaviors like if there is no address provided.

Anyway, in these 2 cases, we want to be able to provide feedbacks to the API caller, saying that we saved everything but probably there is something bad with the address and also, why not, in case of scenario #2, provide the different options sent back by Google MAPS so that the user can pick the right one if he wants and modify the global resource.

In order to do that, we feel like a warning section would be helpful. As we want to follow JSON API Standard, we decided to add a “warning” section inside meta that looks like error section. But we are wondering if we can’t have it at root level like for error in future version.

Thanks for your feedback!

Thomas

2

Hmm, I think the utility of this in the spec is greatly tied to the work on bulk / batch requests. Your reasoning is sound, but I think the field is unnecessary without a resource being structured / designed with multiple intended and coupled effects.

In your case, I would suggest modifications to the resource itself would be the more appropriate solution. For example the location field could contain a location object which has warnings as part of its representation.

In the big picture of supporting bulk / batch requests, I think you could contribute this to the discussion of failure state mitigation.

3

Hi Michael

Thanks for your proposal, I think attaching it to the field is a good idea.

Thomas

1 Like