For our first TOMP-interview, we had an interesting conversation with Eddy Borremans, software architect for Nazza: a Linux/Java based software integrator in the mobility domain. They offer a cloud based back office system for renting bikes, cars and parking space. Nazza operates internationally, but is mostly active in the Netherlands. Using the TOMP-API, they developed, for instance, a system for Arriva that allows customers to book electric folding bikes.[1] During the interview, Eddy told us about his role in the development of the TOMP-API, the main challenges and the future of this standard to communicate between Transport Operators and MaaS Providers.
TOMP-WG – Eddy, when have you discovered TOMP and how did you contribute to the development of this standard?
EB – I have joined the TOMP Working Group in 2019. Due to my early involvement, I have been able to exert some influence on the development of this standard. This was mostly based on our own experiences with TOMP’s shortcomings at the time for our business model. To make it more concrete: one of the less straightforward features of our model is that we utilize the concept of late assignment. This means that you can book an asset, such as a shared bike,[2] but the assignment of the actual asset is deferred until pick-up time. Initially, TOMP did not have such a feature. Among others, our requirements in this regard have influenced the standard of the availability endpoints as well as the booking endpoints.
At the same time, our company had already been developing a booking framework for the MaaS-domain for scenarios in which MaaS-providers would inquire several different independent transport operators in order to offer their end customers a product that is a combination of different, unrelated transport operators. In this scenario, the MaaS-provider tries to book multiple assets, but only wants to do so when all required assets are guaranteed to be available. To facilitate this, our API offered a multiphase booking process that provides a kind of transaction mechanism for assets where the MaaS-provider can rollback and commit bookings as it were. Our approach was taken over by the TOMP Working Group and resulted in the now widely used two phase booking flow.
Implementing TOMP
TOMP-WG – Which challenges did you and Nazza face while implementing TOMP?
The way we handle access to assets in our business model, posed another challenging concept to deal with in TOMP. One of our unique selling points is that once a rental (leg) has started, our customers can operate (open and close the locks) the asset without the need to be connected to the internet. This is for instance very convenient when you need to park your bike in areas where there is little or no internet connection. This feature is included in our app, which makes use of a custom developed Bluetooth API to communicate with the locks. The architecture behind this prevents the app from being able to call TOMP for initiating or terminating a rental. Instead, our app and back-office work together to initiate or terminate a rental, and notify TOMP of these events via trip execution call-backs. Simply put, as we do not want to rely on an internet connection, we do not involve TOMP in real time, but we do send information related to this rental afterwards.
At Nazza we also offer services to external parties. For instance, some of our customers want to provide their assets to other MaaS-providers. In that case, the provider can book assets with our customers via our TOMP API. However, since our Bluetooth technology has superior capabilities, the MaaS-providers are required to use our app for accessing the assets. It turns out it is far from easy to develop your own Bluetooth API to communicate with our assets. We try to facilitate access to our app as transparently as possible by providing deeplinks that are used by the MaaS-providers’ proprietary app to defer control to our app when starting and ending rentals and when opening or closing locks. Initially, TOMP did not offer deeplinking in the form that we needed for our services. Thanks to the input of our company, the TOMP Working Group added this feature in version 1.3. One of the challenging aspects of this was that we had to customize our 0.5.0 implementation in order to deal with this shortcoming. Anyone familiar with implementing and using standard API’s knows that it can cause quite a headache to keep everything synchronised, especially when external customers make heavy use of your API’s.
In any case, over the years we did quite a few implementations. Mostly based on version 1.3. Working on these implementations generated yet more feature requests and bug reports from our side towards the standard.
TOMP-WG – You already have a lot of experience in implementing TOMP. What are your main observations regarding this for the field as a whole?
EB – What struck me as a member of the TOMP Working Group is that many integration parties that you work with sometimes have trouble adhering to the TOMP standard. Even when they do, they tend to use their own interpretations of how TOMP flows should function. You should know that TOMP only enforces data formats and not behaviour. The TOMP Working Group tries to mitigate this by providing guidance in the way of documentation, but since the behaviour cannot be enforced, you see many TOMP-dialects appearing. One of my roles in in the TOMP Working Group and as the chair of Working Team 2 and to a lesser extent as member of the Change Advisory Board, is to discuss these scenarios, point at real life TOMP challenges internally and with integrators, and provide solutions and use cases for them. One of the current challenges of the Working Group is to find a way to minimize the number of, and prevent the inadvertent distribution of these dialects. This is something that we hope to address in the TOMP version 2.x.
TOMP-WG – Based on your experiences, which are the best practices you would like to share with the community?
EB – I think that you need to start small: there is no need to implement all endpoints at once in order to develop a viable TOMP integration. When integrating the standard or planning to do so, it is recommend to read the TOMP documentation. It will help you to understand the intended behaviour of TOMP flows. When you stick to the intended behaviour, subsequent implementations (with new parties) will be much easier, and you will achieve what TOMP was intended for.
It is also important to avoid adding your own features. If your business model requires certain features, you can always get in touch with the Working Group to discuss these or post feature requests on our Github wiki. As I illustrated earlier, the Working Group is open to examining what is feasible and adding features. I would also recommend documenting all your technical agreements with integration parties, for instance URLs, authentication, call-backs, flow details, pricing, invoicing, etc. Not formalising these elements can lead to a lot of time-consuming confusion during the development and testing phase. Another suggestion is to automate your integration tests: this will optimize your development cost when upgrading to newer TOMP versions.[3] Specifically for MaaS-providers, it is useful implement a double-check mechanism based on the journal entry endpoint. This will allow you to know what invoices to expect from the transport operators.
Lastly, I would like to invite everyone who is interested to join the Working Group and to take part in one or more working teams. This will allow you to stay on top of the latest developments and exert influence on the development of the TOMP-API!
The future of TOMP
TOMP-WG – On a regular basis, the Working Group releases new versions. Would you consider adopting the next major version of TOMP-API?
EB – Well that is an interesting question! From our experience at Nazza, we know that implementing standardized interfaces can be quite a challenging exercise, and if you do not know what you are doing, the entire operation can become rather costly. Breaking an interface towards your customers can be disastrous! Deploying a next version to your customers and ensuring they are all going to use it can also be a challenge. Personally, I expect the next major TOMP version upgrade to contain many breaking changes.[4] Even though the new features provided in the next iteration may solve many issues, fully re-implementing the API while simultaneously maintaining older versions, is not an easy task. I am not sure that every implementer is yet up to this. Therefore, our company would probably postpone upgrading to a major version until one of our projects or customers requires us to do so.
TOMP-WG – If resources were unlimited, what would you want to see next for the TOMP-API?
EB – I could think of a few things. One example is a working reference implementation for all supported versions, which can be publicly used for testing and learning purposes. Furthermore, it would be nice to have automated certification in the next TOMP-API. For instance, having an automated bot that can automatically inquire a party’s API to verify to what extent it complies with TOMP. Next to this, having different endpoints for different purposes would be interesting as well. Currently, the trip execution endpoint is used for two different purposes, namely updating a leg and communicating that a leg has been updated. These are essentially different operations that each should have their own endpoint. The endpoints can be simplified as well. Some of them try to support a too wide variety of use cases. This sometimes results in data structures with numerous fields of which I am not sure if anybody is using them. I may be wrong and too biased based on my company’s requirements, but in my opinion, the current situation unnecessarily clutters and complicates the API. At the same time, however, I do admit that our own requirements regarding deeplinking are actually one of the more complicated additions to the standard. Finally, it would be good to have more extensive technical documentation regarding the most common use cases as well as on the more complex ones.
TOMP WG – To end this interview, Eddy, what would you wish for your industry regarding TOMP?
EB – For my industry to broadly adopt TOMP and to actively participate in its future development!
TOMP-WG – Thank you very much Eddy for your time as well as for your highly appreciated contribution to the TOMP Working Group!
The Hague / Ghent, 14.06.2023
This interview was made possible with the support of the Interreg North Sea Region Programme and the Province of Oost-Vlaanderen (Belgium) as part of the Interreg ShareDiMobiHub project.
[1] https://www.oogtv.nl/2021/11/arriva-stalt-eigen-elektrische-deelvouwfietsen-op-hoofdstation/#:~:text=De%20beschikbaarheid%20van%20de%20deelfietsen,als%20waar%20hij%20is%20gehaald.
[2] In the initial implementation, assets at Nazza were primarily bikes. However, it can also be a car, parking space, charging station, train seat, etc. Every transport operator – in the broad sense of the term as this include parking companies as well – is free to determine which type of assets they want to offer.
[3] One of the principles of test-driven development is that the earlier in the development process, you find a defect, the cheaper it is to repair it. Automated testing helps you finding defects before deploying an application to production. You can very easily, and at a low cost, repeat these tests. It ensures that defects are often found before deployment and can be fixed in time as opposed to defects found by your customers. The latter is usually much more costly to fix due to: customer communication, potential customer damage, defect reproduction, fixing, re-testing, redeployment cost, etc.
[4] A breaking change in an API refers to a change in an endpoint of the ‘server’ party that forces the ‘client’ party to change their ‘calling’ software. This is usually what happens when you change the data format used in an endpoint. When developing an API, you make certain assumptions about what is needed by the system. Your data format is based on those assumptions. Over time, however, your insights in what is needed change and you will have to change the data formats. This will result in a breaking change. A breaking change means that client parties have to change their side of the software as well. As this involves cost and resources, developers will try to keep the number of breaking changes at a minimum.