search

openactive / open-booking-api

Repository for the Open Booking API specification
Other
2 stars 3 forks source link

Clarification required: should remainingAttendeeCapacity include leases? #156

Open nickevansuk opened 4 years ago

nickevansuk commented 4 years ago

The Booking System must ensure that the data returned to the Broker in the remainingAttendeeCapacity and remainingUses properties are up-to-date, including places already booked and those currently reserved by any Leases from competing OrderQuotes, but excluding those places already reserved for this Order UUID by previous calls to C1 and C2. -- https://openactive.io/open-booking-api/EditorsDraft/#step-by-step-process-description

If the OrderItem is repeated (for multiple attendees) this error must only be included in the API response against the OrderItems which are in excess of the capacity but which are reserved by the lease of another Customer - for example in an Opportunity with a remainingAttendeeCapacity of 3, with 1 additional space held by another lease, then for an OrderQuote with 9 OrderItems related to it, this error would only be emitted against 1 of the OrderItems, with OpportunityHasInsufficientCapacityError emitted against the other 5 of the OrderItems. -- https://openactive.io/open-booking-api/EditorsDraft/#order-creation-orderitem-errors

Feedback

The above appears to be a contradiction, and it is also unclear whether the remainingAttendeeCapacity value in the open RPDE feeds should include leases or not.

Clarification required

The specification logic is actually agnostic to whether or not remainingAttendeeCapacity in the open RPDE feed includes leases in its total. Evidently excluding leases from this figure will encourage customers to enter a booking journey with inventory that is potentially unavailable, however this also might encourage more bookings of such inventory (the same argument UX vs sales argument used when a booking system is deciding whether to support leasing in the first place).

The specification should be updated to clarify that e.g. "remainingAttendeeCapacity": 1 in the open RPDE feed does not guarantee availability for that item, as either (i) the item may be booked by another customer in the split second before a call to C1 is made or (ii) the item is actually already leased by another OrderQuote. These scenarios are functionally the same, and in both cases the remainingAttendeeCapacity and remainingUses, and the errors returned by C1, will clarify the situation regarding availability, especially using the OpportunityCapacityIsReservedByLeaseError. If the booking system chooses to provide a better UX, reducing the remainingAttendeeCapacity for leases will reduce the frequency of a user encountering OpportunityCapacityIsReservedByLeaseError.

The specification should be further clarified to make clear that the RPDE feed may or may not include leasing in its totals, but that the remainingAttendeeCapacity and remainingUses values returned from C1 and C2 MUST include the number of spaces that the user can currently select (i.e. taking into account leases, as per the spec quote above). The objective of this is to provide the user with a clear indication of the number of spaces available (the number for which they can expect a booking to succeed) taking into account those that are leased, otherwise they are forced to use a trial-and-error approach to see how many spaces are available to book at the present time. If they try to book more than the number of spaces stated as available in C1 or C2, an OpportunityCapacityIsReservedByLeaseError will inform them that there is contention for any space that is leased (which might encourage them to try again later).

The specification should be updated with a recommendation that the Broker SHOULD display the remainingAttendeeCapacity and remainingUses values returned from C1 and C2 to the user in any user interface that allows amendments to the number of OrderItems for the same opportunity that are included in an OrderQuote.

nickevansuk commented 4 years ago

Having remainingAttendeeCapacity take into account leasing within the RPDE feed can be added as a "SHOULD" in the Open Booking API, to encourage a better user experience, or should it actually be a "MUST" to avoid UX ambiguity/variance across providers?

nickevansuk commented 4 years ago

"For the avoidance of doubt, this must include accurate pricing and live availability information." is included in https://openactive.io/delivering-openactive, so in fact this should probably be a MUST so that the two are aligned.

On reflection this is different from the UX vs Sales argument referenced above, as in this case it is just about data accuracy.

nickevansuk commented 4 years ago

Also for OrderProposals, the spec should clarify that an OrderProposal may not reduce the remainingAttendeeCapacity be design, for cases where a single space is made available to multiple Customers, and the Seller can approve one and reject the others.

This is in the current spec, but its implications may not be obvious:

A Lease is not required for this flow, as in some cases Sellers may prefer to manage contention for spaces manually via the approval process instead of leasing. -- https://openactive.io/open-booking-api/EditorsDraft/#proposal-leasing

Hence any solution to this issue should also clarify OrderProposal.

nickevansuk commented 3 years ago

The tooling has implemented the following:

The remainingAttendeeCapacity value in the open RPDE feeds should always include leases. This ensures data accuracy and optimises the user experience.

The spec should also clarify that the remainingAttendeeCapacity values at C1 and C2 exclude the current lease, and that the remainingAttendeeCapacity value at P and B should not be included (as they have little utility, and add additional complexity to the implementation if they are to be accurate)