search

openactive / open-booking-api

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

Consistent OrderItem `@id`s #196

Open nickevansuk opened 3 years ago

nickevansuk commented 3 years ago

There is no consistent identifier between OrderItems in P and B, which makes it impossible for brokers to track changes between them if they have attached their own metadata to individual OrderItems.

Within OrderItems, Replace:

This property is required for B responses and must not be included for C1, C2 or P responses.

With:

This property is required for B and P responses, and in the Orders feed. It must not be included for C1 or C2 responses.

Add rationale to the Order Endpoint RESTful Semantics to explain that OrderItem @ids must remain constant in structure throughout the whole flow (i.e. "appending #/orderedItem/{orderItemId} to the @id of the Order") even when no order yet exists. From a JSON-LD perspective, the same OrderItems are transferred from the OrderProposal, to the final Order, and hence they each have a canonical JSON-LD @id that does not change throughout the process. Hence they do not need to be given a fresh ID.

Also consider clarifying this requirement, to make it clear that the item in the Orders feed must have a different "id" to the OrderProposal (to ensure that if the Order is cancelled soon after being created, the deletion of the OrderProposal is still registered by the Broker).

The Broker stores the response to B to completely replace their previously stored OrderProposal, and the previous OrderProposal is set to "state": "deleted" in the Orders feed.

nathansalter commented 3 years ago

Isn't this exactly what the position required property is for? So that brokers can keep track of which OrderItem is which?

nickevansuk commented 3 years ago

position is only for within the request / response (and hence is not persisted), rather than tracking more generally:

The position of an OrderItem in the response must match the position for the same OrderItem provided in request, and implementations must use this value to match responses with requests instead of relying on the order of the elements in the array. This is required for C1, C2, P and B requests and responses, but must not be persisted or be present in the Orders feed or other endpoints.

They represent the position only, and there is no implication that the underlying implementation should maintain these as any kind of @id. In fact if a lease was created for an OrderItem in position 0, that lease should still be applicable to the same OrderItem if it was moved to position 1.

Additionally following the JSON-LD @id pattern, any assigned ID should be in URL format.