Adding Access Method As Root Element To POST Bookings-One-Stop And Booking Additional Information In TOMP API

Introduction

This document addresses the feature request to include the accessMethod as a root element in the POST Bookings-One-Stop and Booking Additional Information within the TOMP API. This enhancement aims to provide Transportation Operators (TOs) with clarity on which accessMethods are utilized when booking an asset, such as a bike in a bike-sharing scenario. Currently, the absence of a dedicated field necessitates the use of meta-fields, which is considered less clear and requires a separate field for better clarity and efficiency. Let's delve into the details of the problem, proposed solution, and alternative considerations.

Problem Statement

The core issue lies in the ambiguity surrounding the accessMethods employed during asset booking. As a TO, it is crucial to know the specific accessMethod used to book an asset. For instance, in bike sharing, different accessMethods entail varying operational logic. Consider the following scenarios:

• QR Code: When a user books a bike via QR code, no distance check is performed, and the bike unlocks immediately. The user's position is not required for this accessMethod.
• Number Pad: Conversely, if a user employs a number pad, a position check becomes necessary. The TO must implement the logic to verify the user's location before granting access.

Without a designated field for accessMethod, TOs are compelled to rely on meta-fields or extraInfo, which is a less than ideal solution. This approach lacks clarity and necessitates parsing through additional data to extract the relevant information. This ambiguity can lead to inefficiencies and potential errors in the booking process. Therefore, a clear and explicit method for identifying the accessMethod is essential for streamlined operations.

Proposed Solution

To address the aforementioned problem, the proposed solution involves introducing an optional field, accessMethod, at the root level of the one-stop-booking request and booking request. This field would explicitly indicate the accessMethod used for the booking, eliminating the need for TOs to interpret meta-fields or extraInfo. The possible values for this field would correspond to all accessMethods defined within the asset object. This ensures consistency and clarity in the data transmitted via the TOMP API.

By implementing this solution, TOs can readily determine the accessMethod employed for each booking, enabling them to apply the appropriate business logic. For example, the TO can instantly identify whether a QR code or number pad was used and execute the corresponding procedures, such as skipping the distance check for QR code bookings or performing the check for number pad bookings. This direct approach reduces complexity and improves the efficiency of the booking process. Furthermore, the addition of a dedicated accessMethod field enhances the overall clarity and usability of the TOMP API.

Urgency

The urgency of this feature request is classified as Major. While the TOMP API functions as advertised, the absence of a dedicated accessMethod field necessitates the use of meta-fields. This workaround is not ideal as it introduces ambiguity and requires additional processing to extract the relevant information. A dedicated field would significantly improve the clarity and efficiency of the booking process. Therefore, implementing this feature is considered necessary to enhance the usability and functionality of the TOMP API. The current reliance on meta-fields is a suboptimal solution that warrants a more explicit and standardized approach.

Alternatives Considered

Before proposing the addition of a dedicated accessMethod field, an alternative approach was considered: utilizing the extraInfo field. This would involve including the accessMethod as a key within the extraInfo field, with the value representing the specific accessMethod used. While this approach is feasible, it presents several drawbacks compared to the proposed solution. The extraInfo field is intended for additional, non-core information, and overloading it with essential data such as the accessMethod can lead to confusion and make the API less intuitive to use.

Furthermore, relying on the extraInfo field requires TOs to parse and interpret the data within this field, adding complexity to the booking process. In contrast, a dedicated accessMethod field provides a clear and direct way to access this information, simplifying the implementation for TOs. Therefore, while the extraInfo field could be used as a workaround, it is not the optimal solution. The proposed addition of a root-level accessMethod field offers a more explicit, efficient, and user-friendly approach.

Possible Implementation

While a detailed implementation plan is beyond the scope of this feature request, the general approach would involve modifying the TOMP API schema to include the optional accessMethod field in the one-stop-booking request and booking request. The field should be defined as a string, and the possible values should align with the defined accessMethods within the asset object. This ensures consistency and avoids ambiguity. The API documentation should be updated to reflect the addition of this new field, including a clear explanation of its purpose and possible values. On the server-side, the implementation would involve processing the accessMethod field when it is present in the request and using it to determine the appropriate business logic.

This implementation should be designed to be backward-compatible, meaning that existing clients that do not send the accessMethod field should continue to function correctly. The field is optional, so its absence should not cause errors. However, TOs are encouraged to start using the field as soon as it is available to take advantage of the improved clarity and efficiency it offers. The implementation should also include appropriate validation to ensure that the value of the accessMethod field is valid and consistent with the asset's defined accessMethods.

Benefits of the Proposed Solution

The addition of the accessMethod field as a root element offers several key benefits:

1. Clarity: Explicitly identifies the accessMethod used for booking, eliminating ambiguity.
2. Efficiency: Streamlines the booking process by providing direct access to the accessMethod information.
3. Consistency: Ensures a consistent approach for handling different accessMethods.
4. Usability: Improves the overall usability of the TOMP API by making it more intuitive.
5. Flexibility: Accommodates various accessMethods and their associated business logic.
6. Maintainability: Simplifies the maintenance and evolution of the API by providing a clear and standardized way to handle accessMethods.

These benefits collectively contribute to a more robust, efficient, and user-friendly TOMP API, ultimately enhancing the experience for both TOs and end-users.

Conclusion

The proposed addition of the accessMethod field as a root element in the POST Bookings-One-Stop and Booking Additional Information is a valuable enhancement to the TOMP API. It addresses the current ambiguity surrounding accessMethods in booking requests and provides a clear, efficient, and consistent solution. By implementing this feature, TOs can streamline their booking processes, reduce complexity, and improve the overall usability of the API. The Major urgency classification underscores the importance of this feature in enhancing the functionality and clarity of the TOMP API. While alternatives were considered, the dedicated accessMethod field offers the most effective approach for addressing the problem. The benefits of this solution extend beyond the immediate use case, contributing to the long-term robustness and maintainability of the API.

Keywords

accessMethod, TOMP API, booking, one-stop booking, Transportation Operator (TO), bike sharing, QR code, number pad, meta-field, extraInfo, API schema, implementation, feature request, clarity, efficiency, consistency, usability, flexibility, maintainability.