I 2 Support for stateless offers booking processes - UnionInternationalCheminsdeFer/OSDM GitHub Wiki

Description

Support for stateless offers/booking processes.

Owner

  • Nieuwerth Johan (Sqills)
  • Schinor Normen (DB)
  • Bayer Ralf (DB)

Business Value

For customers

who do something

the solution

is a something – the ‘how’

that provides this value

unlike competitor, current solution or non-existing solution

our solution does something better — the ‘why’.

Business Outcomes

The measurable benefits that the business can anticipate if the epic hypothesis is proven to be correct.

To do

Leading Indicators

The early measures that will help predict the business outcome hypothesis.

To do

Nonfunctional Requirements

Nonfunctional requirements (NFRs) associated with the epic.

To do

Ideas

Input Sqills

Concerning statelessness of the OSDM API, the following three functional / principal points arise with regards to the OSDM API specs as they are today:

  1. ID's to refer to parts of trips / offers / etc. should not be UUID's, but should be a free-format string that the Server can use to put in any (hashed) content

    This is a pretty basic point, but it's a must-have for us to avoid keeping state. The ID's can grow quite long with this concept and they will certainly not be default UUIDs anymore, but they would still have the precise same functional meaning in the schemas.

    The server is responsible: where S3 Passenger or the DB system might put a very long string in there, others may still indeed put in a UUID. For client systems, it should not make a difference, as they should never interpret the actual value of the ID anyway (nor try to decipher it).

  2. The current API is a bit too restful; we should cut down on the number of endpoints: retrieving very small parts of a journey search result makes it unnecessary complex

    This topic is a bit more sensitive maybe, but in our discussion we concluded that we have too many REST pattern based endpoints, which do not really make sense to a client and in fact may only make the overall API appear more complex than it actually is.

    Both DB and Sqills basically never "Split up" a total Journey Search, so while the OSDM spec may suggest you should be able to fetch the Reservation details of one segment within one Offer within one OfferCollection within one Trip of one TripCollection, our gut feeling is that clients don't really need that.

    The whole stateless / ID problem topic becomes much bigger, if we have to make much more "smart hashes" to point out individual components.

    Amadeus, for example, has confirmed that they would never fetch this small individual components of a total offer, there is no use case for that.

    We also observed in our call with DB that even Javascript clients in e.g. React, would have some local datastore, so should be able to simply grab the entire result...

  3. We should stop allowing patching of elements like passengers or seats / seat preference on offers, while they actually belong to the bookings instead.

    In a stateless system, there are no offers to patch. It seems like the OSDM spec now only supports this as a sort of "remote data store", so that clients don't have to keep track of some passenger details or seat preferences locally.

    During booking of an offer, the booking system would then need to fetch these values from the offer. In both the Sqills and DB system, in reality, these values are actually natively part of the booking request itself.

    We also observed that for stateful clients that need to update their offer, an OSDM API spec where this input is part of the Booking, can still achieve that.

    The other way around is much harder. For example, if the OSDM POST / Bookings API would include the seat prefer / passenger update input in the request, a carrier that internally needs to update the Offer could do so as a 1st internal step, where the booking is then the 2nd internal step.

    If we go the other way around, that would force e.g. Sqills and DB to design state on these offer updates, which is one of the hardest things to implement OSDM in fact.

    Here also, Amadeus has confirmed that from their perspective as a distributor, there is no real purpose on updating the offer, and they could also send along these things in the booking request.

Attached, you can also find a slide deck (Google Slides) with some more background information on these topics: https://docs.google.com/presentation/d/1dnXCsIYFdTYBbo60Prpm8il7Q5g6J6rJfXyUaBXHZBE/edit?usp=sharing

Input BENE

Point 1 is fine. As you mentioned, clients should never look into it so it actually does not really impact the standard

Point 2 is indeed more provocative (-; I am - as you noticed - quite attached to leaving a door open for the highest possible REST maturity level. I understand that the consensus in the group today is different. However, in order to have a standard that

  1. can both accommodate this collegial standpoint .and a more front-end/mobile oriented approach where much smaller bits of data are relevant at a time
  2. takes into account the evolutions of the technologies such as HTTP/2 (and its multiplexing & resource push capabilities)

I believe the embed mechanism is the proper balance between this current demand and the points I just mentioned

Point 3 is an interesting debate. While I would at first disagree with your proposal of pushing the passenger data capture in the post booking itself (or in the booking as it is now, since the point is precisely that some pax data may be needed to book), I do agree that patching the offer structure directly can be tricky (although there are potential solutions with secondary keys etc). However, an alternative would more for me go towards an intermediary structure, not in the booking yet. But this is indeed something to be discussed.

Input SBB: Distinction Capability API vs. Experience-Specific API

From PayPal API Style Guide

Logically, we can segment the services and the APIs that they expose into two categories:

  1. Capability APIs are public APIs exposed by services implementing generic, reusable business capabilities.
  2. Experience-specific APIs are built on top of capability APIs and expose functionality which may be either specific to a channel, or optimized for a context-specific specialization of a generic capability. Contextual information could be related to time, location, device, channel, identity, user, role, privilege level among other things.

Capability-based Services and APIs

Capability APIs are public interfaces to reusable business capabilities. Public implies that these APIs are limited only to the interfaces meant for consumption by front-end experiences, external consumers, or internal consumers from a different domain.

Experience-based Services and APIs

Experience-specific services provide minimal additional business logic over core capabilities, and mainly provide transformation and lightweight orchestration to tailor an interaction to the needs of a specific experience, channel or device. Their input/output functionality is limited to service calls.