Warnings in a REST API as not critical errors

Question

I have a REST API that for some of entpoinds like DELETE, POST or PUT I have some validation rules that can return an error.

Now I need a new type of an error like a non-critical error, that it should fail in a normal way, but should go for the action if there is a "supress warnings" flags send. Such an user can be asked: "Are you sure want to change this status, you are not finished yet"

Question: is there a best practice for these type of errors?

Secondary questions:

• Are there any HTTP semantic for such behaviour that I can user?
• do I still follow REST idea (for me it looks I do) - I keep it stateless

• try-catch-finally: How do you decide whether to show such a warning to a user? You call an API endpoint to check the application status and then present the user such a dialog, blocking the UI until the user responds. Then you make the actual call. You should model this with you REST API too: add an endpoint to check whether it's save to do certain tasks. This way any API user is able to make "pre-flight" checks and even delegate decision to a user. Your HTTP status code approach is like a rm /file that "warns" the file is readonly while deleting it anyway.
• Laiv: This happens when business is overlapped with protocol status code. Anyways. Did you try to use your own 'HTTP status code? If Twitter can, you too. Lets say for example 6xx? Anyways so far I know, you can add messages into the response body even if it's 4xx (which range would be apropiated in your case).
• user237329: Finally I used 409 CONFLICT for warning response. This way, the client is instructed that it can force the call with the same endpoint and body with an exttra parameters "force=1"

Answer 1

There are no warning result codes in http, you either return a success (200) or an error (400, 500). The only thing I know of that could be analogous to what you want is something like code 401 'unauthorised' - which is an outright failure, but causes most clients to automatically re-attempt connection with credentials.

For a REST API you need to tell the server the status of the request and how to handle the result - you cannot send a PUT and expect an error if the client is not finished, or success if it has - the server needs to know this information in order to send back the right result code.

So you can send the 'suppress warnings' flag with your request, if it is not set the server would return a 409 error code (or similar), and if set, return a 200 code instead. The user cannot be asked 'do you want to change this status' after the status change is sent.

You could make a request to the server to ask if the user can change status of course and follow with an appropriate request after that.

• Arc: I'm in no way saying it's the right thing to do, but 3xx codes could be seen as some sort of notice or warning code where the client may decide to proceed. That said, I'd rather either perform an action or I don't, and maybe I return a response with additional information in the returned body or in headers.

Answer 2

If you wish to permit the user to override your normal error handling, you can consider returning a 200 SUCCESS status with additional information in extended HTTP headers. For example, you could return

X-APP-STATUS: 422 Unprocessable entity
X-APP-SOURCE: Invalid ID 'fo0'

This would give your client-side code the information necessary to either warn the user or take corrective actions on its own.

• gbjbaanb: I never liked responses that say "I successfully failed" :-)
• icc97: @gbjbaanb Perhaps this answer uses an actual error, but the concept that is being described is useful. Instead of Invalid ID it could be something like Age is over 100, is DoB correct?.
• icc97: As in a 'warning' is not 'successfully failed'. Its something like 'I succeeded but maybe you still want to undo what happened'.

Answer 3

We have rules that provide hard and soft errors (hard errors can’t be bypassed, soft errors are, essentially, the warnings described in the OP).

On post (create a transaction), we return the errors (hard and soft). If the consumer wants to proceed, the transaction request is resubmitted with "acceptedErrors": [...]" and the rules will proceed if ALL soft errors are accepted and ther are no hard errors.

We do also have a validate and submit ‘helper’ endpoints to clarify the workflow. There are some security / integrity issues with this, though. The consumer can, but really shouldn’t submit a list of common errors (essentially a default accept). So it might, or might not, be too risky an approach. Our endpoints are guarded / internal, so we have insight into our consumers that ‘public’ apis may not.

• user237329: hi @Kristian , thank you for sharing your idea. It looks to be a clever solution, having acceptedErrors. For us that would be too "much" for how we implement our clients.... but I see many usages. Kudos
• Kristian H: @user237329 Thanks. It isn't a universally applicable approach, but it does allow us to maintain the stateless requests between validate and submit. There are some other complexities, in that sorta race conditions may exist between validate and submit (not bugs / defects, but depending on time intervals, real state changes may occur, which can affect the validation) and we know, and expect that, but some domains may not appreciate it.

Answer 4

I decided to return a 200 OK response with a boolean in the response on the warning type. We wanted to check if a similar request was done 'recently' or not when creating a report. The business logic for whether it is recent or not is held in the backend.

The API returns the response with the boolean flag isRecent and creates the record. However the frontend can then decide what it wants to do with this flag.

For us we pop-up a warning modal that allows them to 'undo' the creation.