Request Success With Warning

[jlnaps]

While the context is different, we are in a situation similar to this StackOverflow thread:

https://stackoverflow.com/questions/35149401/rest-endpoint-with-success-and-a-helpful-warning

We have a request that we want to succeed, but we also want to return information to the user to inform them that they are in a potentially bad state and should probably get out of it. The responses to that thread generally conclude that there isn't really a standard way to do this with REST and it should be application specific. They suggest either returning some kind of header or something in the Response body.

Is this something we would want to put into the API standards so all SPS APIs would return this kind of information in a similar manner? Or do we think it can remain application specific?

EDIT: It is also possible this is a bad idea and we shouldn't do it. I'm open to that as an answer as well.

[travisgosselin]

At first glance, this seems "application specific" to me. It does remind me of other scenarios similar that show warnings though. For example:

• We use a header to indicate the CORS warnings that occurred to be more specific, but have no response body on OPTIONS, so there isn't a great alternative here.
• Prism proxy, for example, returns Open API violations (warnings) as a header sl-violations where you call the API and it returned a result but was a mismatch from the spec (https://docs.stoplight.io/docs/prism/beeaad4dc0227-prism-cli#proxy).

From the sounds of it though these situations warrant this kind of intercepted addition to the response header where there is no alternative. In your case, it sounds like you have an application-specific message/intent, which drives me to think its not a standard header but is part of your response body as implied in StackOverflow responses.

However, if you can provide more specific details on the use case it might shed a bit more light on it. Thoughts?

[nicholas-s-perkins]

I would wonder how you could generalize this.
If there is some action the client has to do something about, I would think it would depend on what exactly the response to the warning would be.
Most returns tend to reduce to "I can move forward" (2xx), "I can retry" (5xx) or "I'm dead" (4xx).

Even in those simple cases, clients still have to decide what to do in a way. Like 404 is the weird case and sometimes means an app does another action, sometimes not.
While our standards can imply what range of behaviors an app might have, responses to those behaviors are often particular to a specific app SLA.