How can you enforce a "do you really want to do this" confirmation in a publically exposed API?

Question

Is there a commonly (or rarely) used pattern for a "confirming you want to do this" message when calling a function from a library?

I have a API that exposes some operations that are potentially dangerous if misused (would cause unwanted changes to the database). I would like to pass a warning back to the caller to double check that this is on purpose. This is both to guard against other programmers in the organization misusing the API and to prevent an end-user from accidentally executing this command from a form without thinking about it.

There are really three use cases for this API function:

1. Execute it against legit data. Should succeed with no warnings.
2. Execute it against bad data. Should fail with an exception.
3. Execute it against questionable data. The validate logic sees that it is a non-standard case, but maybe the end user knows what they are doing and is doing this on purpose.

I have been trying to think of a way to put case 3 into my API.

One way I have thought of revolves around a "confirmation token"

Sub DoRiskyOperation(thisData As String, Optional confirmationToken As ConfirmationToken)

    If Not Validate(thisData) Then
        Throw New ArgumentOutOfRangeException("thisData", $"Cannot perform this operation on {thisData}.")
    End If

    If Not confirmationToken.ItsOK Then
        If Not TotallySafe(thisData) Then
           Throw New Warning("thisData", $"Are you sure you want to do this?", _
                             New ConfirmationToken(AreYouSure))
        End If
    End If

    'perform risky operation

End Sub

Another way I was considering is more of an "ask first" which is sometimes frowned upon:

Enum PredictedSuccess
    WillSucceed
    WillFail
    WillSucceedButIsRisky
End Enum

Private LastDataAskedAbout As String

Function IsOperationRisky(thisData As String) As PredictedSuccess

    LastDataAskedAbout = thisData
    If Not Validate(thisData) Then Return PredictedSuccess.WillFail
    If TotallySafe(thisData) Then
        Return PredictedSuccess.WillSucceed
    Else
        Return PredictedSuccess.WillSucceedButIsRisky
    End If
End Function

Sub DoRiskyOperation(thisData As String)

    If Not Validate(thisData) Then Throw New ArgumentOutOfRangeException("thisData", $"Cannot perform this operation on {thisData}.")

    If Not TotallySafe(thisData) AndAlso LastDataAskedAbout <> thisData Then
        Throw New InvalidOperationException($"Hey, you were supposed to check before you try doing something this dangerous to {thisData}!")
    End If

    'perform risky operation

End Sub

Is there another way to encode the concept of this "confirmation handshake" into an API that I am not thinking of?

In case anyone is interested, the specific use - case is updating standard cost while there is inventory on hand. Accountants are picky about these kind of things.

Answer 1

You're trying to solve a human factor problem with an API-level solution, and I believe it's not going to work. It is most likely the case of XY problem.

If the "risk" is losing the data because someone did something stupid (or malicious), you should eliminate this possibility (of data loss) altogether. There should be no "risky" methods whatsoever, because human mistakes are not something you can eliminate.

---

The correct ways to do that may be:

1. Fool-proofing: Make it so that backup is created, or the data is only being marked as deleted, and not actually deleted, etc.
2. Dangerous UI function (as opposed to API change): Add a confirmation dialog to the UI, with huge, bold capital letters saying "YOU'RE ABOUT TO DELETE ALL THE DATA". Also, make sure you log this operation in a proper way, so you always can find the angry employee who deleted your database then they got fired.
3. Access-control: make a risky operation only available to people who are responsible for possible damage. Make sure they understand the risk. Don't give access to anyone else.

Answer 2

I use your first approach but without throwing anything. The subroutine takes one extra argument, like yours - "I know this is risky but do it anyway", and it returns three possible values:

• Success
• Failure
• Blocked because it's risky and the caller didn't say "do it anyway".

Apart from your use case, this is also useful for the case where the operation is something that may or may not require authorisation (such as a password). In that case the extra argument is the authorisation token, and the third return value is "Blocked because the token is missing or invalid". This adapts very nicely to the case where the calling program sometimes remembers authorisation tokens for reuse.

Answer 3

Confirmation is not really appropriate for an API. The point of "are you sure?" confirmations is to allow a human user to think twice before performing a potentially destructive operation. An API is called by code, so any form of confirmation will have to programmed into the client from the beginning, thereby making the warning moot.

You suggest the confirmation could be passed on to a user interacting with the client. But this breaks separation of concerns. The whole point of an API is that it does not care if it is called as part of a manual operation or if it is called through a script or whatever.

So forget the "confirmation token", and instead design the API in such a way that it communicates clearly to client developers that a certain operation is potentially dangerous. For example, you might have two version of a call:

DriveForwardIfSafe()
DriveForwardIgnoreAllWarnings()

This communicates very clearly to the client developer that one version is potentially unsafe, and the developers deciding to call the "unsafe" version will be doing so informed.

Answer 4

Confirmation dialogs aren't normally an API concern, they're a UI concern, because it pertains to letting a fallible, inconsistent human change their mind or correcting for mis-keys and mis-clicks before committing their actions.

That said, there are exceptions to the norm.

Many services provide history and/or undo functionality, for example. In the case where the API is far removed from the actual end user, or when the interactions themselves need to be fluid and efficient, store some level of history and permit undo operations.

And if, for whatever reason, the operation were totally irreversible, like launching a missile, your API should demand an authorization code, possibly a single-use code -- and possibly from multiple users. But, that would likely be collected during the initial dangerous call -- you wouldn't throw an exception in to warn the user of the danger. The presence of the auth token signifies that.

Answer 5

I would require an additional grant for the operation. E.g. the operation can only be executed if you have su. And su can only be granted temporarily. So to invoke this operation you would need to request temporary su permission first then invoke the operation before su expires.