Include expected fee before an action

[nichtich]

For renrew an additional document field "renewfee" could be added, but fees for renewals are rare. To find out the fee of a request, an additional method or parameter is required. The fee depends on patron, document, and time, so the fee cannot be provided via DAIA.

[nichtich]

Fees may also apply to requests or even cancel actions.

[nichtich]

We could return information about consequences of an action (request, renew, and cancel) to be confirmed with a repeatable field doc.confirm?:

• confirm.about (0..1) - textual description or message
• confirm.amount (0..1) - expected fee as amount of money
• confirm.type (0..1) - URI to identify the type of consequence

The existence of a doc.confirm field should imply a doc.error.

To approve the action, the client must add a new request parameter confirm:

• confirm=true : perform action whether confirmation id required or not. Response never includes field doc.confirm
• confirm=false : don't perform action no matter if confirmation required or not. This is helpful to check whether some action requires confirmation or not. Response may include field doc.confirm.
• default behavior if no confirm parameter is given: perform action if no conformation is required. don't perform action otherwise. Response may include field doc.confirm.

Current clients don't know about this parameter so they will just get an error (doc.error) for actions that require confirmation.

[JonathanRowell]

I would have thought that a message containing a "please confirm" note would produce a reply message which is either empty, meaning the resubmitted request would proceed without problems, or when not empty, a string to be displayed with the query "do you want to do it". The resubmitted request would not include the "please confirm" marker. This would then be compatible with existing clients (incidentally how many of them are there???) and flexible enough for all eventual possibilities.

[nichtich]

Still to be discussed. See https://github.com/gbv/paia/wiki/Confirmations for an alternative proposal with more flexibility.

[JonathanRowell]

Far too complicated. It seems like one has taken a leaf out of NCIP's book, but without the actual "scheme" construction. A proposal which leaves questions open is incomplete. And why are you trying to squeeze all error replies into an HTTP response code? A REST interface can use HTTP response codes because it contains no semantics. Here the semantics are very complex and the error returns must be explanatory, so HTTP response codes are inappropiate.

[nichtich]

Far too complicated. It seems like one has taken a leaf out of NCIP's book, but without the actual "scheme" construction. A proposal which leaves questions open is incomplete.

We have two requirements:

• patrons should need to confirm some actions because of fees
• patrons should need to or be allowed to choose from a list of storage locations for some actions

I strongly bet that soon there will be more requirements of confirmations, e.g.

• show an additional warning on short-term loan
• let users select from a list of loan periods for renewals
• confirm priority requests (e.g. professor may directly get a book although it had already been requested by 5 students. let professor know about this)
• ...

Libraries can be very creative with loan conditions!

And why are you trying to squeeze all error replies into an HTTP response code? A REST interface can use HTTP response codes because it contains no semantics. Here the semantics are very complex and the error returns must be explanatory, so HTTP response codes are inappropiate.

ok, it was just an option question whether HTTP 402 Payment Required may be helpful. I have updated https://github.com/gbv/paia/wiki/Confirmations also including some comments of a colleague.

[nichtich]

This feature turned out to be more complex but it is truly optional, backwards-compatible and covers two required use cases (confirmation of fees and selection of pick-up locations).