New top level object: "warnings"

[mattholden]

Presently, the spec allows for a top level item of 'data' or 'errors' but not both. Therefore, unless you cram something nonstandard into the meta object, there is no way to provide feedback to the user/developer that the request was executed, but with warnings.

Example use cases for warnings include:

• The endpoint you called has been deprecated
• Data provided in the request was truncated or formatted during processing
• You tried to create a duplicate entity, so we did an upsert and returned the existing one
• Certain attributes were hidden from the response due to scope permissions

All of these are valuable for the developer to know, but JSON:API doesn't give us anywhere official to put them.

Under this proposal, API developers MAY return a top-level 'warnings' key in responses (there is no reason to submit POST data with a warning.) It would be permitted regardless of whether 'data' or 'errors' is present. The 'warnings' key, if present, MUST be an array containing one or more Warning Objects.

A Warning Object should have the same schema as an Error Object, less the 'status' key.

[jelhan]

Thank a lot for your proposal! To be honest I'm skeptical about it. But let me share some thoughts how it could be implemented using an extension in v1.1 anyways.

An extension can define additional members of the top-level document:

An extension MAY define new members within the document structure defined by this specification.

The name of a member defined by an extension must be prefixes with a namespace:

The name of every new member introduced by an extension MUST be prefixed with the extension’s namespace followed by a colon (:).

That means it could not just be warnings, but it could be warnings:warnings if that extension registers warnings as its namespace.

Maybe it would be good to extend scope a little bit and support other debug information like info as well. In that case a broader namespace like debug may be more appropriate.

All of these are valuable for the developer to know, but JSON:API doesn't give us anywhere official to put them.

In most cases APIs are meant to be consumed by computer programs. Not sure if API response is the best way to communicate with the developers who are developing clients consuming them.

In my experience developers inspect the API response only if changing how client consumes that API or if debuging an issue, which might be related to an API response. So I wouldn't expect that such a warning is noticed by a developer at all.

Additionally it comes with a noticable trade-off of increased payload size. Avoiding to send data, which is not needed, over the wire (over-fetching), is one of the most hyped features of GraphQL.

[ben221199]

I think about adding some level attribute to the error object is better:

{
	"errors":[
		{
			"title": "This is a warning",
			"detail": "We are testing a warning error type.",
			"level": "warning"
		},
		{
			"title": "This is a debug thing",
			"detail": "We are testing a debug error type.",
			"level": "debug"
		}
	]
}

[AndyEMIS]

I agree with @jelhan that API responses are not necessarily the best way to communicate with developers, but that only pertains to the "deprecated" use case. All of the other use cases mentioned by @mattholden can be handled by the client to inform the end user.

Another use case is where there is a non-fatal error that prevents the API from returning some data (perhaps where a downstream service is unavailable), but the API can still return meaningful and useful data to the client. In this scenario the client needs to know that some data may be missing.

In my opinion, it would be extremely useful to either have a top-level warnings object or to amend the specification to allow both data and errors objects to be returned in the same response.

[DeclanClose]

So.... pitching in here as I've got an interest in this one also :-)
You're all right, well sort of.
All error and non-error information should go into logs somewhere with errors being reported back to the caller somehow - whether the caller is a UI or some middle-man process.
However there are occasions where the caller does need both the data - as it has been changed and committed to the database but also to be informed of other non-error information and react in some way because it needs to act on that in some way, such as notify a user.
Typically such scenarios come about where we are interfacing with systems outside of our control or having to obey legacy or legal rules that we cannot override because they don't fit neatly into our chosen framework.

Ideally the "errors" structure would be expanded into a "messages" structure of which "errors" is but one, but in the meantime going down the extension route seems the most common sense approach, use that to fine tune it into a workable solution then propose it get adopted into the main spec at some point.
I'm thinking of the "atomic:operations" extension when I say that.
So then I propose we define an extension for "messages" which at the very least includes a "messageType" attribute, the "message" and I think it should also include as a minimum a timestamp attribute. Anything else can go in the message itself or in a "meta" section (per message).
Anyone interested in pitching in with this, beyond Emis? As I was typing "I propose...." I suddenly felt a chill and a sense of the jaws of a trap closing in on me and a voice saying "ok, go on then, you do it...." :-P But it was just my imagination, wasn't it?

[ben221199]

Situation one:

• Add multiple new members, like warnings, info and debug to the top object.

Situation two:

• Start allowing errors next to data in the top object.
• Add a level attribute to each error object. Omitting this attribute would default to some defined level, likely error.

Situation three:

• Something else.

[jelhan]

I see it as unlikely that support to the base specification is added before having experience with solutions implemented as extensions. I recommend focusing on achieving what you need in one or more extensions for the time being.

[freddrake]

On Fri, Sep 1, 2023, 06:34 Ben ***@***.***> wrote: Situation two: - Start allowing errors next to data in the top object. - Add a level attribute to each error object. Omitting this attribute would default to some defined level, likely error.

This seems unreasonable given the compatibility promises. An existing client might not be able to tolerate responses that combined data and errors, because detecting errors could, reasonably, cause days to be ignored and the entire response is handled badly. Many developers would quickly be confused by getting errors back with successful response codes. Using a new warnings member that's allowed with either data or errors seems best. -Fred

…

[AndyEMIS]

I see it as unlikely that support to the base specification is added before having experience with solutions implemented as extensions. I recommend focusing on achieving what you need in one or more extensions for the time being.

That is understandable, thank you @jelhan. If we create an extension, is there a way of putting it forward for inclusion on the jsonapi.org website?

Is anyone on this thread interested in collaborating to create an extension? If so, then perhaps we should move this discussion to https://discuss.jsonapi.org/ (I believe that is the correct place for discussions about extensions)