search

gbv / paia

Specification of Patrons Account Information API (PAIA)
http://gbv.github.io/paia
15 stars 12 forks source link

Missing specification of response content for cancel function #66

Closed domerz closed 1 year ago

domerz commented 7 years ago

The specification of the cancel method in PAIA (https://gbv.github.io/paia/paia.html#cancel) does not specify the type of result documents it should return. Is that

  1. the list of canceled holds or
  2. the list of remaining holds after cancelling

Both versions seem to be equally plausible even considering the 1..n quantity restriction, since we could easily respond with an empty document when cancelling the last remaining hold.

ndege commented 6 years ago

I like to attach me to the issue. Even for me the interpretation of specification at this position is really ambiguous. I would prefer to go advance and discuss it soon. Thanks for your efforts in advance!

ndege commented 6 years ago

@nichtich To get to a conform response scheme for several services I would like push this issue again?

nichtich commented 6 years ago

I fear that given that the response was not specified from the beginning, we can hardly put additional constraints but only add a recommendation with SHOULD. I'd expect to return the same documents as send with the cancel request as the set of uncanceled documents is already returned via items request. What would you prefer?

ndege commented 5 years ago

It's a bit a question to think about unbiased and carefully. As my propose for balancing fees https://github.com/gbv/paia/issues/69 it's necessary to decide if you return all items which are affected by the action or not which normally corresponding to another existing PAIA action. At first sight it seems to be familiar to get back all affected items because normally we do an second request to repopulate our renewed list with items. But indeed the question would be it is truly necessary? For the other choice returning all unaffected items one have to ask if it delivers all necessary means to detect and report errors if anything fails by the action?

nichtich commented 5 years ago

Sorry for not making this clear earlier. The renew method has more specific information about its response, I can copy this note to the cancel method as well:

The response SHOULD include the same documents as requested. A client MAY also use the items method to get the service status after renewal.

On a closer look this is of little value: because of the SHOULD clause a client must check and submit an items request anyway because there is no guarantee the response will include the documents requested.

To answer the original question:

  • the list of canceled holds

Yes, this SHOULD be included (but it's no MUST, so not useful anyway)

  • the list of remaining holds after cancelling

This MAY be included in addition to the cancelled items, but I'd prefer to not.

I tend to raise the SHOULD to a MUST in a next version of PAIA spec, so the response MUST include the same documents as requested. The result of cancellation can be seen by document fields status (e.g. 0 after cancellation or another value if cancellation pending or failed) and error (if cancellation failed). Same applies for method renew.